Sui Agent Wallets

Sui Agent Wallets Skill

MCP tool: When available in your environment, also query the Sui documentation MCP server (https://sui.mcp.kapa.ai) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Source constraint: All information sourced from docs.sui.io and docs.waap.human.tech. Each reference file cites the specific page it is derived from.

An agent that holds a private key can be talked out of it. Prompt injection, a poisoned tool result, or a malicious NFT in the agent's own inbox are enough, and the published incidents of an agent losing funds share a shape: the key was reachable from the agent's context, so the agent's judgment was the only control standing between an attacker and the money.

This skill covers the alternative on Sui: the agent holds no key, and the limits are enforced beneath the agent rather than by its own code. In WaaP Squid Mode on Sui that authority is a capability object, which means the permission to sign is onchain state a Move package can gate, not a config file the agent can edit.

The most common AI-coding mistakes it prevents:

• Putting a private key or seed phrase in an agent's environment, prompt, or tool output, then trying to control spend with instructions.
• Assuming a spend limit enforced in agent code is a security boundary. It is documentation. An agent that can edit its own config can raise its own limit.
• Treating a policy refusal as terminal when it is an escalation to a human.
• Treating Sui like an account-based chain when the authority is an object.
• Assuming a delegated scope is permanent, or that it can be recalled early. It expires, and the expiry is the control.

This skill routes to focused reference files. Load only the ones relevant to the current task.

If unsure about any command, run waap-cli commands --json. It emits the authoritative machine-readable command schema for the installed version, and the docs recommend it over any page or --help when generating automation. Do not guess or extrapolate from other SDKs or wallet CLIs.

Sui fundamentals are not repeated here. For Programmable Transaction Blocks, the object model, and client configuration, load the official ptbs, object-model and sui-client skills.

Reference files

setup — Provisioning an agent wallet on Sui

Path: setup.md Load when: creating an agent's wallet for the first time, provisioning signing on Sui, funding an account, or wiring the CLI into a container. Covers: account creation, the Sui capability object, the two curves and which chains sit on each, what the account must hold before it can sign, session isolation for concurrent agents, and which package versions carry which commands.

policy — Limits that the agent cannot raise

Path: policy.md Load when: adding spend limits, approval steps, or any control on what an agent may do with funds. Covers: where the policy gate sits, what it checks before a signature exists, the daily spend limit and what crossing it actually does, the human approval step, and why an in-agent check is not a boundary.

delegation — Scoped, expiring authority

Path: delegation.md Load when: the agent must act repeatedly without prompting a human each time, or a scope has to be granted to a sub-agent or a third party. Covers: minting and spending a Privilege from the CLI, scopes bound to recipients, chain, a cumulative ceiling and an expiry; the maximum lifetime and the much shorter default; the difference between a session and a standing mandate.

Routing guide

Skill Content

Key concepts

The agent holds no key. Keys are generated and used inside secure hardware and never reach the agent's machine, container, or context. There is no key in an env var, no seed phrase in a file, and nothing in a tool result that can be exfiltrated by convincing the agent to print it.

In Squid Mode the authority is a Sui object. What the account holds is a capability object on Sui. Signing is gated on that object, which is why the permission is onchain state rather than a server-side flag. It is transferable, so the user is not locked to one operator, and because it is an object a Move package can wrap it and impose its own conditions before a signature is requested. This is specific to Squid Mode; the standard mode signs in secure hardware and has no capability object.

Two curves, one account. One login provisions two curves: secp256k1 for EVM chains and ed25519 for Sui and Solana. The same account therefore signs on Sui and on other chains without a second wallet. The addresses are native on each chain, and nothing is moved between them.

⚠️ Curve compatibility is not chain availability. A chain sitting on one of those curves is reachable without new cryptography, but each still needs transaction formatting and network plumbing. Live today: EVM, Sui and Solana. Do not tell a developer an account can transact on any chain on either curve.

The gate sits in front of the key, not around it. Every signing request is checked server-side before a signature exists: the exact transaction bytes are verified, the policy engine returns one verdict, and the approval is single-use and bound to that one request. An agent cannot route around a check it never performs.

--chain is required on every signing command. There is no global default chain set is deprecated and stores nothing. A transaction always names the network it is going to.

Rules

1. Never put a private key or seed phrase where an agent can read it. Not in an environment variable, not in a prompt, not in a file the agent's tools can open. If a design requires this, the design is the bug.
2. Never treat an in-agent spend check as a control. Write the limit where the agent cannot reach it. An agent that can edit its config can raise its own limit, and an agent under prompt injection will be asked to.
3. Scope every delegated grant on all four axes: which recipients, which chain, a cumulative ceiling, and an expiry. A grant missing any one of them is broader than it looks.
4. Handle escalation, not just refusal. Crossing the daily limit raises an approval request rather than failing outright. An agent that treats that as a terminal error stops working the first time it does its job.
5. Never pass a Privilege in argv. --privilege-stdin reads it from stdin so it stays out of shell history, ps output, and logs.
6. Default to dry run. An agent that can spend should ship not spending. Turning spending on is a decision with a number attached, not a flag someone forgets to set.
7. Fund the account before the first signature. On Sui the signature settles onchain, so the account needs SUI for gas. A WaaP Squid Mode account also needs IKA for the signing network's fee. An unfunded account fails in a way that reads like a bug in your code.
8. Say what is live. EVM, Sui and Solana today.

Common mistakes

Storing a key "just for the agent's hot wallet." The amount does not change the shape of the failure, only its size. Use an account whose key the agent never sees.

Enforcing the limit in the loop. A check inside the agent's own code runs after the agent has decided. The limit has to be evaluated by something the agent does not control, on the request, before the signature exists.

Retrying an escalation. A request that comes back waiting for authorization is not a failure to retry in a loop. It is a human being asked. Wait for it, or surface it.

Granting an unbounded scope because it is convenient. A grant with no recipient allowlist can pay anyone. Bound it, and let it expire.

Expecting a standing mandate. A scoped grant is a session, not a subscription. Its maximum lifetime is enforced server-side and the default is far shorter than the maximum, so a monthly billing flow cannot be built by granting once and forgetting. See delegation.md.

Assuming the wallet is scoped to your app. It is not. The same account works in the next application the user visits, which is a feature for the user and a thing to remember when reasoning about balances your app did not create.

Confusing the signing network with Sui itself. In Squid Mode the signature is completed by an independent validator network together with secure hardware; Sui is where the authority object lives and where the transaction settles. They are different parties doing different jobs.