Skip to main content
Choose which of your wallets (wal_*) each agent (agt_*) can move money from, and which one it spends from by default. For the model behind grants, read the The Wallet Access object. Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key. These routes manage both your own agents and agents you have already connected through an invitation. Use your customer account’s user session or API key. Agent keys and developers acting on your behalf cannot change access. Connected-agent changes additionally require delegations.update alongside the route’s wallet permissions. Accepting an invitation grants one wallet, which becomes the connection’s default. Add more wallets here after acceptance; adding a wallet preserves the existing default.

Attach an agent

Attach the agent with POST /wallets/{walletId}/agents, passing the agent’s id. Attach an ACTIVE agent to an active standard wallet. Attaching the Vault returns wallet.vaultNotAllowed; attaching again returns alreadyExists.
The response carries the agent, with meta.walletAccess.isDefault and meta.walletAccess.accessType (owned or connected):
You cannot attach an agent to the Vault. See Use the Vault.

Set the default wallet

Set it with POST /wallets/{walletId}/agents/{agentId}/default; it is the wallet the agent spends from when a call names none. The first attached wallet becomes the default. For a connected agent, this default belongs to your customer connection and is independent of the agent’s other customers and its developer. Pass walletId to use another granted wallet. An unusable default fails the call; Natural does not substitute another wallet. Money addressed directly to an agent still goes to its developer-owned default wallet. Customer-connected wallets do not change that destination.

List the agents a wallet allows

Confirm with GET /wallets/{walletId}/agents which owned and connected agents can use a wallet, and whether it is the default for each agent. Connected entries return this connection’s limits, omit the developer’s private metadata and activity, and identify the developer through the party relationship. This route only covers wallets your party owns. A connected customer’s wallet returns 404, even to the developer of an agent attached to it. As that developer, list the customer wallets your agent can use with GET /wallets, passing customerPartyId and authenticating with the agent’s key.

Detach an agent

Revoke access to this one wallet with DELETE /wallets/{walletId}/agents/{agentId}. This requires wallets.update and agents.read, plus delegations.update for connected agents. The response contains the full agent and meta.deleted: true; the marker refers to its wallet access. The agent stays active on every other wallet it is attached to. You cannot detach an agent from its own default wallet (wallet.defaultCannotBeDetached): point its default at another wallet first. A connected agent therefore keeps at least one granted wallet. To remove all access, revoke the customer connection instead.