> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Give an agent wallet access

> Give agents access to wallets to move money

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](/guides/concepts/wallet-access).

<Snippet file="shared/prerequisites.mdx" />

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`](/api-reference/wallets/grant-agent-access-to-wallet), 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`.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```bash CLI theme={null}
  natural wallets attach-agent \
    --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
    --json '{"agentId": "agt_019cd1798d637a4da75dce386343931d"}' \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  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" }
      }
    }'
  ```
</CodeGroup>

The response carries the agent, with `meta.walletAccess.isDefault` and `meta.walletAccess.accessType` (`owned` or `connected`):

<Snippet file="api-examples/wallets.attachAgent.response.mdx" />

<Note>
  You cannot attach an agent to the **Vault**. See [Use the Vault](/guides/wallets/vault).
</Note>

## Set the default wallet

Set it with [`POST /wallets/{walletId}/agents/{agentId}/default`](/api-reference/wallets/set-agent-default-wallet); 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.

<CodeGroup>
  ```python Python theme={null}
  client.wallets.set_agent_default_wallet(
      "wal_019cd1798d714ce765e0486a417c23dc",
      "agt_019cd1798d637a4da75dce386343931d",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  await client.wallets.setAgentDefaultWallet({
    walletId: "wal_019cd1798d714ce765e0486a417c23dc",
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural wallets set-agent-default-wallet \
    --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
    --agent-id agt_019cd1798d637a4da75dce386343931d \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents/agt_019cd1798d637a4da75dce386343931d/default \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>

## List the agents a wallet allows

Confirm with [`GET /wallets/{walletId}/agents`](/api-reference/wallets/list-wallet-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.

<CodeGroup>
  ```python Python theme={null}
  agents = client.wallets.list_agents("wal_019cd1798d714ce765e0486a417c23dc")

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

  ```typescript TypeScript theme={null}
  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);
  }
  ```

  ```bash CLI theme={null}
  natural wallets list-agents --wallet-id wal_019cd1798d714ce765e0486a417c23dc
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

<Snippet file="api-examples/wallets.listAgents.response.mdx" />

## Detach an agent

Revoke access to this one wallet with [`DELETE /wallets/{walletId}/agents/{agentId}`](/api-reference/wallets/detach-agent-from-wallet). 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.

<CodeGroup>
  ```python Python theme={null}
  client.wallets.detach_agent(
      "wal_019cd1798d714ce765e0486a417c23dc",
      "agt_019cd1798d637a4da75dce386343931d",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  await client.wallets.detachAgent({
    walletId: "wal_019cd1798d714ce765e0486a417c23dc",
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural wallets detach-agent \
    --wallet-id wal_019cd1798d714ce765e0486a417c23dc \
    --agent-id agt_019cd1798d637a4da75dce386343931d \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/wallets/wal_019cd1798d714ce765e0486a417c23dc/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.