> ## 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.

# PTB builders

> The transaction builders behind the high-level methods, for composing or inspecting PTBs directly.

The builders return a `@mysten/sui` `Transaction` you sign and submit yourself (with an `Executor`, dapp-kit, or `guardedSubmit`). `AltheiaSui` wraps them; reach for the builders when you want to inspect, dry-run, or compose a PTB before submitting.

All agent-action builders take a `SuiRefs` (from [`agentRefs`](/sdk/altheia#agentrefs)).

## Agent actions

| Builder                         | Move call                                       | Notes                                                     |
| ------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| `buildSwap(refs, amount)`       | `deepbook_adapter::execute_swap_quote_for_base` | Buy: spend the capped quote, receive base into the vault. |
| `buildSellSwap(refs, amount)`   | `deepbook_adapter::execute_swap_base_for_quote` | Sell: unwind a base position back to quote.               |
| `buildPlaceLimit(refs, params)` | `trading_account::place_limit_order`            | Needs `tradingAccount` + `balanceManager` refs.           |
| `buildCancelAll(refs)`          | `trading_account::cancel_all`                   | Needs `tradingAccount` + `balanceManager` refs.           |

```ts theme={null}
import { buildSwap, keypairExecutor } from "@altheia-xyz/sui";

const tx = buildSwap(refs, 50_000_000n);     // 0.05 SUI
const res = await keypairExecutor(client, kp)(tx);
```

### `LimitParams`

```ts theme={null}
type LimitParams = {
  clientOrderId: bigint; orderType: number; selfMatching: number;
  price: bigint; quantity: bigint; isBid: boolean; payWithDeep: boolean;
  expireTimestampMs: bigint;
};
```

## Owner lifecycle

Signed with the owner key; refs must carry `ownerCap`.

| Builder                                                | Move call                      | Notes                                    |
| ------------------------------------------------------ | ------------------------------ | ---------------------------------------- |
| `buildRevoke(refs)`                                    | `vault::admin_revoke_policy`   | Terminal.                                |
| `buildPause(refs)`                                     | `vault::admin_pause_policy`    | Freeze without revoking.                 |
| `buildUnpause(refs)`                                   | `vault::admin_unpause_policy`  | Resume a paused agent.                   |
| `buildSetActions(refs, actionIds)`                     | `vault::admin_set_actions`     | Replace the allowed-action set.          |
| `buildSetValueGuard(refs, maxSlippageBps, baseScalar)` | `vault::admin_set_value_guard` | Global swap price-band.                  |
| `buildKillDrain(refs, ownerAddr, coinTypes?)`          | revoke + drain                 | Revoke and sweep the vault to the owner. |

`buildKillDrain` drains the held coin types. Pass `coinTypes` from `vaultBalances` to drain exactly what the vault holds — draining a type with no balance aborts.

## Provisioning

`provisionAgentMulti(exec, params)` composes the whole agent in one owner signature: vault, deposit, policy, asset cap, value-guard, agent cap, and an agent gas top-up. It returns `{ vault, ownerCap, policy, cap }`. The dashboard does this for you; the builder is for programmatic provisioning.

```ts theme={null}
const prov = await provisionAgentMulti(ownerExec, {
  corePkg, quoteType: "0x2::sui::SUI", agentAddr, ownerAddr,
  fundAmount: 600_000_000n, agentGas: 100_000_000n,
  cfg: {
    agentId: "agent-1",
    perDayCap: 2_000_000_000n,
    perTxCap: 600_000_000n,
    allowedPackages: [poolId],
    allowedActions: [SUI_ACTIONS.deepbookSwap],
    expiresAtMs: 4_102_444_800_000n,
    swapMinRate: 15_000_000n,
  },
});
```

### `SuiPolicyConfig`

| Field             | Type            | Notes                                                                  |
| ----------------- | --------------- | ---------------------------------------------------------------------- |
| `agentId`         | `string`        | Label, becomes `agent_id` on chain.                                    |
| `perDayCap`       | `bigint`        | Required. Max cumulative spend per rolling 24h, base units.            |
| `perTxCap`        | `bigint?`       | Per-tx ceiling. `0` disables the per-tx check.                         |
| `allowedPackages` | `string[]`      | Protocol scope (package/pool ids).                                     |
| `allowedActions`  | `SuiActionId[]` | Capability allowlist, default-deny.                                    |
| `expiresAtMs`     | `bigint`        | Absolute expiry.                                                       |
| `swapMinRate`     | `bigint?`       | Min output per input unit ×1e9. Required if `deepbookSwap` is allowed. |

### `SUI_ACTIONS`

```ts theme={null}
const SUI_ACTIONS = { transfer: 0, deepbookSwap: 1, deepbookLimitOrder: 2, deepbookCancel: 3 };
```

<Card title="Chain reads" icon="arrow-right" href="/sdk/reads" horizontal>
  Read the live policy, vault balances, and the audit log straight from chain.
</Card>