Give an agent wallet access

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 Wallet access overview. 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 vault_not_allowed; attaching again returns already_exists.

import uuid
from naturalpay import Natural

client = Natural()
grant = client.wallets.attach_agent(
    "wal_019cd1798d714ce765e0486a417c23dc",
    agent_id="agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
)
print(grant.data.id)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const grant = await client.wallets.attachAgent({
  walletId: "wal_019cd1798d714ce765e0486a417c23dc",
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
});
console.log(grant.data.id);

natural wallets attach-agent \
  --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
  --json '{"agentId": "agt_019cd1798d637a4da75dce386343931d"}' \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": { "agentId": "agt_019cd1798d637a4da75dce386343931d" }
    }
  }'

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.

client.wallets.set_agent_default_wallet(
    "wal_019cd1798d714ce765e0486a417c23dc",
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
)

await client.wallets.setAgentDefaultWallet({
  walletId: "wal_019cd1798d714ce765e0486a417c23dc",
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
});

natural wallets set-agent-default-wallet \
  --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
  --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents/agt_019cd1798d637a4da75dce386343931d/default \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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.

agents = client.wallets.list_agents("wal_019cd1798d714ce765e0486a417c23dc")

for agent in agents.data:
    print(agent.id, agent.attributes.name, agent.meta.wallet_access.is_default)

const agents = await client.wallets.listAgents({
  walletId: "wal_019cd1798d714ce765e0486a417c23dc",
});

for (const agent of agents.data) {
  console.log(agent.id, agent.attributes.name, agent.meta.walletAccess.isDefault);
}

natural wallets list-agents --wallet-id wal_019cd1798d714ce765e0486a417c23dc

curl https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Detach an agent

Revoke access to this one wallet with DELETE /wallets/{walletId}/agents/{agentId}. The agent stays active on every other wallet it is attached to. You cannot detach an agent from its own default wallet (default_wallet_cannot_be_detached): 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.

client.wallets.detach_agent(
    "wal_019cd1798d714ce765e0486a417c23dc",
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
)

await client.wallets.detachAgent({
  walletId: "wal_019cd1798d714ce765e0486a417c23dc",
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
});

natural wallets detach-agent \
  --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
  --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)"

curl -X DELETE https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Overview

Common use cases

Products

Guides

Give an agent wallet access

Attach an agent

Set the default wallet

List the agents a wallet allows

Detach an agent

​Attach an agent

​Set the default wallet

​List the agents a wallet allows

​Detach an agent

Attach an agent

Set the default wallet

List the agents a wallet allows

Detach an agent