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

# Wallets

> Create and manage your wallets

Wallets holds your money on Natural. You can open multiple to keep funds separate: payroll separate from operating cash, or a dedicated pool per agent.

## Create a wallet

Create a new wallet with [`POST /wallets`](/api-reference/wallets/create-wallet).

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

  client = Natural()
  wallet = client.wallets.create(
      idempotency_key=str(uuid.uuid4()),
      display_name="Payroll",
      description="Dedicated wallet for payroll runs",
  )
  print(wallet.data.id)
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural();
  const wallet = await client.wallets.create({
    idempotencyKey: crypto.randomUUID(),
    displayName: "Payroll",
    description: "Dedicated wallet for payroll runs",
  });
  console.log(wallet.data.id);
  ```

  ```bash CLI theme={null}
  natural wallets create \
    --idempotency-key "$(uuidgen)" \
    --display-name "Payroll" \
    --description "Dedicated wallet for payroll runs"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/wallets \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "displayName": "Payroll",
          "description": "Dedicated wallet for payroll runs"
        }
      }
    }'
  ```
</CodeGroup>

<Note>
  The API only creates `standard` wallets. The **Vault** is set up automatically, never through the
  API. See [Vault](/guides/wallets/vault).
</Note>

A new wallet starts empty. Fund it by [depositing from a linked bank account](/guides/transfers/deposit-and-withdraw), or [transfer money in from another of your wallets](/guides/transfers/transfer-between-wallets).

## Check a balance

List all walletes in one call to [`GET /wallets`](/api-reference/wallets/list-wallets) and get details with [`GET /wallets/{walletId}`](/api-reference/wallets/get-wallet).

<CodeGroup>
  ```python Python theme={null}
  wallets = client.wallets.list()
  for wallet in wallets.data:
      balance = wallet.attributes.balance
      available = balance.available if balance else 0
      print(wallet.id, wallet.attributes.display_name, available)
  ```

  ```typescript TypeScript theme={null}
  const wallets = await client.wallets.list();
  for (const wallet of wallets.data) {
    console.log(wallet.id, wallet.attributes.displayName, wallet.attributes.balance?.available ?? 0);
  }
  ```

  ```bash CLI theme={null}
  natural wallets list
  ```

  ```text MCP theme={null}
  What is my wallet balance?
  ```

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

Each wallet carries two figures: available and total. available is what you can spend now, with total including pending transfers and holds. Generally you should always opt for using available balance.

<Snippet file="shared/cents-note.mdx" />

To read one wallet, pass its id to [`GET /wallets/{walletId}`](/api-reference/wallets/get-wallet):

<CodeGroup>
  ```python Python theme={null}
  wallet = client.wallets.get("wal_550e8400e29b41d4a716446655440000")
  balance = wallet.data.attributes.balance
  print(balance.available if balance else 0)
  ```

  ```typescript TypeScript theme={null}
  const wallet = await client.wallets.get({
    walletId: "wal_550e8400e29b41d4a716446655440000",
  });
  console.log(wallet.data.attributes.balance?.available ?? 0);
  ```

  ```bash CLI theme={null}
  natural wallets get --wallet-id wal_550e8400e29b41d4a716446655440000
  ```

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

## Rename a wallet

Rename a wallet or change its description with [`PATCH /wallets/{walletId}`](/api-reference/wallets/update-wallet).

<CodeGroup>
  ```python Python theme={null}
  wallet = client.wallets.update(
      "wal_550e8400e29b41d4a716446655440000",
      idempotency_key=str(uuid.uuid4()),
      display_name="Operating (US)",
      description="Primary USD operating wallet",
  )
  ```

  ```typescript TypeScript theme={null}
  const wallet = await client.wallets.update({
    walletId: "wal_550e8400e29b41d4a716446655440000",
    idempotencyKey: crypto.randomUUID(),
    displayName: "Operating (US)",
    description: "Primary USD operating wallet",
  });
  ```

  ```bash CLI theme={null}
  natural wallets update \
    --wallet-id wal_550e8400e29b41d4a716446655440000 \
    --idempotency-key "$(uuidgen)" \
    --display-name "Operating (US)" \
    --description "Primary USD operating wallet"
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.natural.com/wallets/wal_550e8400e29b41d4a716446655440000 \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{ "data": { "attributes": { "displayName": "Operating (US)", "description": "Primary USD operating wallet" } } }'
  ```
</CodeGroup>

## Set your default

Your default wallet is where Natural puts money when a payment, deposit, or withdrawal omits `walletId`, and where payments to your email, phone, or handle land. Set it with [`POST /wallets/{walletId}/default`](/api-reference/wallets/set-default-wallet).

The default is a party-level setting: exactly one wallet is your party's default, and setting a new one clears the old. Each agent also has its own default, set separately. See [Wallet access](/guides/controls/wallet-access).

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

  ```typescript TypeScript theme={null}
  await client.wallets.setDefault({
    walletId: "wal_550e8400e29b41d4a716446655440000",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural wallets setDefault \
    --wallet-id wal_550e8400e29b41d4a716446655440000 \
    --idempotency-key "$(uuidgen)"
  ```

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

<Note>
  The Vault cannot be your default. Keep a standard wallet as your default so calls that leave out
  `walletId` always resolve somewhere spendable.
</Note>

## Freeze a wallet

Freezing with [`POST /wallets/{walletId}/freeze`](/api-reference/wallets/freeze-wallet) stops money moving in or out while leaving the balance intact. Unfreeze with [`POST /wallets/{walletId}/unfreeze`](/api-reference/wallets/unfreeze-wallet) to return the wallet to `active`.

<CodeGroup>
  ```python Python theme={null}
  client.wallets.freeze("wal_550e8400e29b41d4a716446655440000")
  client.wallets.unfreeze("wal_550e8400e29b41d4a716446655440000")
  ```

  ```typescript TypeScript theme={null}
  await client.wallets.freeze({ walletId: "wal_550e8400e29b41d4a716446655440000" });
  await client.wallets.unfreeze({ walletId: "wal_550e8400e29b41d4a716446655440000" });
  ```

  ```bash CLI theme={null}
  natural wallets freeze --wallet-id wal_550e8400e29b41d4a716446655440000
  natural wallets unfreeze --wallet-id wal_550e8400e29b41d4a716446655440000
  ```

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

<Note>You cannot freeze your party's default wallet. Make another wallet the default first.</Note>

<Snippet file="shared/webhook-wallet.mdx" />