> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altheia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AltheiaSui

> The high-level client, and agentRefs that derives an agent's objects from its key.

`@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`.

```bash theme={null}
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.

```ts theme={null}
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`](/sdk/reads#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

```ts theme={null}
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`

```ts theme={null}
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.

```ts theme={null}
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`

```ts theme={null}
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`                                                      |

<Card title="PTB builders" icon="arrow-right" href="/sdk/builders" horizontal>
  The lower-level builders behind the high-level methods.
</Card>