PTB builders - Altheia

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

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.

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`

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.

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`

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

Chain reads

Read the live policy, vault balances, and the audit log straight from chain.

​Agent actions

​LimitParams

​Owner lifecycle

​Provisioning

​SuiPolicyConfig

​SUI_ACTIONS