Integrate the SDK

The SDK builds the policy-gated transactions; the Move contract enforces the policy. Your agent process holds a private key and calls AltheiaSui methods. The contract decides whether each action lands.

Install

npm i @altheia-xyz/sui

Node 20+. @altheia-xyz/sui re-exports the @mysten/sui primitives an agent needs (SuiJsonRpcClient, getJsonRpcFullnodeUrl, Ed25519Keypair, decodeSuiPrivateKey), so there is one copy of @mysten/sui in play. A dapp-kit executor is provided for browser wallet flows.

Env

The agent needs only its key, from provisioning:

AGENT_PRIVKEY=suiprivkey1...

Construct the agent

agentRefs reads the AgentCap the key owns and derives the vault, policy, and cap. keypairExecutor signs and submits, waiting for finality so sequential actions don’t race.

import {
  SuiJsonRpcClient, getJsonRpcFullnodeUrl, Ed25519Keypair, decodeSuiPrivateKey,
  AltheiaSui, keypairExecutor, agentRefs,
} from "@altheia-xyz/sui";

const client = new SuiJsonRpcClient({ url: getJsonRpcFullnodeUrl("testnet"), network: "testnet" });
const kp = Ed25519Keypair.fromSecretKey(decodeSuiPrivateKey(process.env.AGENT_PRIVKEY!).secretKey);

const refs = await agentRefs(client, kp.getPublicKey().toSuiAddress());
const agent = new AltheiaSui(client, refs, keypairExecutor(client, kp));

agentRefs throws if the address owns no AgentCap — wrong key, or the agent is not provisioned.

Act

const r = await agent.swap(50_000_000n);   // 0.05 SUI, gated by the policy
console.log("landed", r.digest);

swap buys (spends the capped quote, receives base into the vault). sellSwap unwinds a base position back to quote. Amounts are base units. Each method builds, signs, and submits internally.

Handle denials

A policy denial surfaces as a thrown error. decodePolicyAbort tells a policy denial apart from a liquidity or gas failure.

import { decodePolicyAbort } from "@altheia-xyz/sui";

try {
  await agent.swap(2_000_000_000n);     // over the per-tx cap
} catch (e) {
  const ab = decodePolicyAbort(e);
  if (ab) handleDenied(ab.reason_code); // "over_per_tx_cap" | "policy_revoked" | ...
  else throw e;                         // not a policy decision — surface it
}

Denials are normal control flow. A capped agent will hit them.

Record denials without spending gas

A denied action aborts on-chain and emits no event, so to log denials, dry-run first. guardedSubmit dry-runs, records a policy abort to the audit backend, and submits only when allowed.

import { buildSwap, guardedSubmit } from "@altheia-xyz/sui";

const r = await guardedSubmit(
  client, keypairExecutor(client, kp), kp.getPublicKey().toSuiAddress(),
  buildSwap(refs, 50_000_000n),
  { baseUrl, token, agent_id, action_type: "deepbook_swap", amount: 0.05, asset: "SUI" },
);
// r.ok ? r.digest : r.reason_code

Read state

const p = await agent.policy();        // live caps + state from chain
const log = await agent.auditLog(10);  // recent on-chain events

Or read directly with readPolicyObject, vaultBalances, readAuditLog. See the SDK reference.

Runnable example

A DeepBook agent: allowed, denied, revoked.

Get started

Concepts

Guides

SDK reference

Help

Integrate the SDK

Install

Env

Construct the agent

Act

Handle denials

Record denials without spending gas

Read state

Runnable example

​Install

​Env

​Construct the agent

​Act

​Handle denials

​Record denials without spending gas

​Read state

Runnable example

Install

Env

Construct the agent

Act

Handle denials

Record denials without spending gas

Read state