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.

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)

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);

natural wallets create \
  --idempotency-key "$(uuidgen)" \
  --display-name "Payroll" \
  --description "Dedicated wallet for payroll runs"

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"
      }
    }
  }'

The API only creates standard wallets. The Vault is set up automatically, never through the API. See Vault.

A new wallet starts empty. Fund it by depositing from a linked bank account, or transfer money in from another of your wallets.

Check a balance

List all walletes in one call to GET /wallets and get details with GET /wallets/{walletId}.

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)

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

natural wallets list

What is my wallet balance?

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

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. To read one wallet, pass its id to GET /wallets/{walletId}:

wallet = client.wallets.get("wal_550e8400e29b41d4a716446655440000")
balance = wallet.data.attributes.balance
print(balance.available if balance else 0)

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

natural wallets get --wallet-id wal_550e8400e29b41d4a716446655440000

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

Rename a wallet

Rename a wallet or change its description with PATCH /wallets/{walletId}.

wallet = client.wallets.update(
    "wal_550e8400e29b41d4a716446655440000",
    idempotency_key=str(uuid.uuid4()),
    display_name="Operating (US)",
    description="Primary USD operating wallet",
)

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

natural wallets update \
  --wallet-id wal_550e8400e29b41d4a716446655440000 \
  --idempotency-key "$(uuidgen)" \
  --display-name "Operating (US)" \
  --description "Primary USD operating wallet"

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" } } }'

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

client.wallets.set_default(
    "wal_550e8400e29b41d4a716446655440000",
    idempotency_key=str(uuid.uuid4()),
)

await client.wallets.setDefault({
  walletId: "wal_550e8400e29b41d4a716446655440000",
  idempotencyKey: crypto.randomUUID(),
});

natural wallets setDefault \
  --wallet-id wal_550e8400e29b41d4a716446655440000 \
  --idempotency-key "$(uuidgen)"

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

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

Freeze a wallet

Freezing with POST /wallets/{walletId}/freeze stops money moving in or out while leaving the balance intact. Unfreeze with POST /wallets/{walletId}/unfreeze to return the wallet to active.

client.wallets.freeze("wal_550e8400e29b41d4a716446655440000")
client.wallets.unfreeze("wal_550e8400e29b41d4a716446655440000")

await client.wallets.freeze({ walletId: "wal_550e8400e29b41d4a716446655440000" });
await client.wallets.unfreeze({ walletId: "wal_550e8400e29b41d4a716446655440000" });

natural wallets freeze --wallet-id wal_550e8400e29b41d4a716446655440000
natural wallets unfreeze --wallet-id wal_550e8400e29b41d4a716446655440000

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"

You cannot freeze your party’s default wallet. Make another wallet the default first.

Overview

Common use cases

Products

Guides

Create a wallet

Check a balance

Rename a wallet

Set your default

Freeze a wallet

​Create a wallet

​Check a balance

​Rename a wallet

​Set your default

​Freeze a wallet

Create a wallet

Check a balance

Rename a wallet

Set your default

Freeze a wallet