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

# Wallet access

> Give agents access to wallets to move money

## Attach an agent

Attach the agent with [`POST /wallets/{walletId}/agents`](/api-reference/wallets/grant-agent-access-to-wallet), passing the agent's `id`.

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  client = Natural()
  grant = client.wallets.attach_agent(
      "wal_019cd1798d617f65a79cb965dda9eac3",
      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_019cd1798d617f65a79cb965dda9eac3",
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
  });
  console.log(grant.data.id);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/wallets/wal_019cd1798d617f65a79cb965dda9eac3/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": { "agentId": "agt_019cd1798d637a4da75dce386343931d" }
      }
    }'
  ```
</CodeGroup>

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

## Set the default wallet

Your agents can have default wallets.
An agent's default wallet is the one it moves money from when a call names no wallet. Agents getting paid also use the default wallet to collect funds.

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

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

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/wallets/wal_019cd1798d617f65a79cb965dda9eac3/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) exactly which of your agents can move money from a wallet, and which one holds the default.

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

  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_019cd1798d617f65a79cb965dda9eac3",
  });

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

  ```bash cURL theme={null}
  curl https://api.natural.com/wallets/wal_019cd1798d617f65a79cb965dda9eac3/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: point its default at another wallet first.

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

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

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