AltheiaSui

@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 arg	Type	Notes
`client`	`SuiJsonRpcClient`	A testnet client.
`refs`	`SuiRefs`	The deployment + agent object ids. Usually from `agentRefs`.
`exec`	`Executor`	Signs 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.

Method	Action
`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.

Method	Action
`revoke()`	Set the policy `revoked`. Terminal.
`killAndDrain(ownerAddr)`	Revoke and sweep every vault asset to the owner in one transaction.

Reads

Method	Returns
`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.

Object	Id
core package	`0x786dfa134ccb4d5144bacf0998b356aafdef0c99121d8a35ed237627d173d917`
deepbook adapter	`0xac114631b134549c489b4f00ee693b1096a38027473202865bde52b7259ee8b7`
adapter registry	`0xe057edccd17e284c7c1307c7d2b260c29d72d4594bed5f49785f91daa5760d12`
DeepBook pool	`0x48c95963e9eac37a316b7ae04a0deb761bcdcc2b67912374d6036e7f0e9bae9f`
quote type	`0x2::sui::SUI`
base type	`…::deep::DEEP`

PTB builders

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

Get started

Concepts

Guides

SDK reference

Help

`AltheiaSui`

Agent actions

Owner lifecycle

Reads

Example

`agentRefs`

`keypairExecutor`

`SUI_TESTNET`

PTB builders

​AltheiaSui

​Agent actions

​Owner lifecycle

​Reads

​Example

​agentRefs

​keypairExecutor

​SUI_TESTNET

PTB builders

`AltheiaSui`

Agent actions

Owner lifecycle

Reads

Example

`agentRefs`

`keypairExecutor`

`SUI_TESTNET`