Skip to main content
@altheia-xyz/sui is the TypeScript SDK for altheia on Sui. It builds the policy-gated transactions; the contract enforces the policy. The package re-exports the @mysten/sui primitives an agent author needs, so a project imports one package and runs one copy of @mysten/sui. 
npm i @altheia-xyz/sui

​
AltheiaSui

Construct with a client, the agent’s refs, and an executor. Every method builds, signs, and submits internally — the caller never touches a PTB. 
const agent = new AltheiaSui(client, refs, keypairExecutor(client, kp));
Constructor argTypeNotes
clientSuiJsonRpcClientA testnet client.
refsSuiRefsThe deployment + agent object ids. Usually from agentRefs.
execExecutorSigns and submits. keypairExecutor for Node, a dapp-kit executor for the browser.

​
Agent actions

Signed with the agent key. Each returns { digest } and throws if the transaction fails. A policy abort surfaces as a thrown error you decode with decodePolicyAbort.
MethodAction
swap(amount)Buy: spend the capped quote asset, receive base — settles into the vault.
sellSwap(amount)Sell/unwind: spend a base position, receive quote — settles into the vault.
placeLimit(params)Place a gated limit order (needs tradingAccount + balanceManager refs).
cancelAll()Cancel all open orders.
amount is bigint | number in base units. swap(50_000_000n) spends 0.05 SUI.

​
Owner lifecycle

Signed with the owner key. The refs must carry ownerCap.
MethodAction
revoke()Set the policy revoked. Terminal.
killAndDrain(ownerAddr)Revoke and sweep every vault asset to the owner in one transaction.

​
Reads

MethodReturns
policy()A PolicySnapshot of the live policy.
auditLog(limit?)The on-chain audit events for the deployment.

​
Example

import {
  SuiJsonRpcClient, getJsonRpcFullnodeUrl, Ed25519Keypair, decodeSuiPrivateKey,
  AltheiaSui, keypairExecutor, agentRefs, decodePolicyAbort,
} 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));

try {
  const r = await agent.swap(50_000_000n);
  console.log("allowed", r.digest);
} catch (e) {
  const ab = decodePolicyAbort(e);
  console.log("denied", ab?.reason_code);
}

​
agentRefs

agentRefs(client, agentAddr, deploy?, recipient?): Promise<SuiRefs>
Derives the full SuiRefs from just the agent’s address. It reads the AgentCap the agent owns on chain and pulls vault_id, policy_id, and the cap id from it; the package ids, pool, and coin types come from deploy (defaults to SUI_TESTNET). The agent author needs only the key. Throws if the address owns no AgentCap — wrong key, or the agent is not provisioned. 
const refs = await agentRefs(client, agentAddr);
// { corePkg, adapterPkg, dbPkg, registry, vault, policy, cap, pool,
//   baseType, quoteType, deepType, recipient }
ownerCap is empty in the derived refs; supply it when constructing owner-side refs for revoke / killAndDrain.

​
keypairExecutor

keypairExecutor(client, signer): Executor
A Node executor. Signs and submits the built PTB, then waits for finality so sequential transactions from the same signer don’t race on stale gas or object versions. An Executor is (tx: Transaction) => Promise<SuiTransactionBlockResponse>; a dapp-kit browser executor is also provided for wallet-signed flows.

​
SUI_TESTNET

The deployed testnet coordinates — the same for every agent.
ObjectId
core package0x786dfa134ccb4d5144bacf0998b356aafdef0c99121d8a35ed237627d173d917
deepbook adapter0xac114631b134549c489b4f00ee693b1096a38027473202865bde52b7259ee8b7
adapter registry0xe057edccd17e284c7c1307c7d2b260c29d72d4594bed5f49785f91daa5760d12
DeepBook pool0x48c95963e9eac37a316b7ae04a0deb761bcdcc2b67912374d6036e7f0e9bae9f
quote type0x2::sui::SUI
base type…::deep::DEEP

PTB builders

The lower-level builders behind the high-level methods.