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

# Agent Wallet

> Manage agent budgets, enforce spending guards, and handle x402 payments with the Anima Agent Wallet.

# Agent Wallet

The Anima Agent Wallet provides budget management and payment capabilities for AI agents. It combines spending guardrails with the x402 payment protocol so agents can transact autonomously within defined boundaries.

## Core Concepts

* **Budget Guards** -- Configurable limits that prevent agents from overspending
* **x402 Payments** -- HTTP-native payment protocol for agent-to-agent and agent-to-service payments
* **Balance Tracking** -- Real-time tracking of agent spending across all payment methods

## Setting Up a Wallet

<Tabs items={["Node.js", "Python", "Go"]}>
  <Tab value="Node.js">
    ```ts theme={null}
    import { Anima } from "@anima-labs/sdk";

    const anima = new Anima({ apiKey: "ak_..." });

    // Create a wallet for an agent
    const wallet = await anima.wallet.create({
      agentId: "ag_8f3k2m9x1n4p7q6r",
      currency: "usd",
      budgetGuards: {
        dailyLimitCents: 500_00,
        monthlyLimitCents: 5000_00,
        perTransactionLimitCents: 100_00,
        requireApprovalAboveCents: 50_00,
      },
    });

    console.log(`Wallet: ${wallet.id}, Balance: ${wallet.balanceCents}`);
    ```
  </Tab>

  <Tab value="Python">
    ```python theme={null}
    from anima import Anima

    anima = Anima(api_key="ak_...")

    wallet = anima.wallet.create(
        agent_id="ag_8f3k2m9x1n4p7q6r",
        currency="usd",
        budget_guards={
            "daily_limit_cents": 50000,
            "monthly_limit_cents": 500000,
            "per_transaction_limit_cents": 10000,
            "require_approval_above_cents": 5000,
        },
    )

    print(f"Wallet: {wallet.id}, Balance: {wallet.balance_cents}")
    ```
  </Tab>

  <Tab value="Go">
    ```go theme={null}
    import "github.com/anima-labs-ai/go"

    client := anima.NewClient("ak_...")

    wallet, err := client.Wallet.Create(ctx, &anima.CreateWalletParams{
        AgentID:  "ag_8f3k2m9x1n4p7q6r",
        Currency: "usd",
        BudgetGuards: &anima.BudgetGuards{
            DailyLimitCents:          50000,
            MonthlyLimitCents:        500000,
            PerTransactionLimitCents: 10000,
        },
    })
    ```
  </Tab>
</Tabs>

## Budget Guards

Budget guards enforce spending policies at the wallet level. When a payment request exceeds a guard threshold, it is either declined or routed for human approval.

| Guard                       | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `dailyLimitCents`           | Maximum total spend per calendar day                  |
| `monthlyLimitCents`         | Maximum total spend per calendar month                |
| `perTransactionLimitCents`  | Maximum single transaction amount                     |
| `requireApprovalAboveCents` | Transactions above this amount require human approval |
| `allowedMerchantCategories` | Restrict payments to specific MCC codes               |
| `blockedMerchantCategories` | Block payments to specific MCC codes                  |

### Updating Budget Guards

```ts theme={null}
await anima.wallet.updateBudgetGuards("wlt_abc123", {
  dailyLimitCents: 1000_00,
  requireApprovalAboveCents: 200_00,
});
```

## x402 Payments

Anima wallets natively support the [x402 payment protocol](https://www.x402.org/), enabling agents to pay for HTTP resources by including payment headers.

<Tabs items={["Node.js", "Python"]}>
  <Tab value="Node.js">
    ```ts theme={null}
    // Make an x402 payment to access a paid API
    const response = await anima.wallet.payAndFetch({
      walletId: "wlt_abc123",
      url: "https://data-provider.example/api/report",
      maxPaymentCents: 500,
    });

    console.log(`Paid: ${response.paymentCents} cents`);
    console.log(`Data: ${response.body}`);
    ```
  </Tab>

  <Tab value="Python">
    ```python theme={null}
    response = anima.wallet.pay_and_fetch(
        wallet_id="wlt_abc123",
        url="https://data-provider.example/api/report",
        max_payment_cents=500,
    )

    print(f"Paid: {response.payment_cents} cents")
    print(f"Data: {response.body}")
    ```
  </Tab>
</Tabs>

## Checking Balance and History

```ts theme={null}
// Check current balance
const balance = await anima.wallet.getBalance("wlt_abc123");
console.log(`Available: $${(balance.availableCents / 100).toFixed(2)}`);
console.log(`Spent today: $${(balance.spentTodayCents / 100).toFixed(2)}`);

// List transactions
const txns = await anima.wallet.listTransactions("wlt_abc123", {
  limit: 20,
  startDate: "2026-03-01",
});
```

## API Reference

| Endpoint                                               | Method | Description                    |
| ------------------------------------------------------ | ------ | ------------------------------ |
| `https://api.useanima.sh/api/wallet`                   | POST   | Create a wallet                |
| `https://api.useanima.sh/api/wallet/:id`               | GET    | Get wallet details and balance |
| `https://api.useanima.sh/api/wallet/:id/budget-guards` | PUT    | Update budget guards           |
| `https://api.useanima.sh/api/wallet/:id/pay`           | POST   | Initiate a payment             |
| `https://api.useanima.sh/api/wallet/:id/transactions`  | GET    | List transactions              |
| `https://api.useanima.sh/api/wallet/:id/x402`          | POST   | Make an x402 payment           |

## Configuration

| Variable                        | Default | Description                                |
| ------------------------------- | ------- | ------------------------------------------ |
| `ANIMA_WALLET_DEFAULT_CURRENCY` | `usd`   | Default currency for new wallets           |
| `ANIMA_WALLET_X402_ENABLED`     | `true`  | Enable x402 payment protocol support       |
| `ANIMA_WALLET_APPROVAL_WEBHOOK` | --      | Webhook URL for approval-required payments |

## Next Steps

* [A2A Protocol](/a2a/overview) -- Agent-to-agent payments and task delegation
* [Audit Log](/security/audit-log) -- Track all wallet transactions