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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Wallet transfers

> Move money from one of your users to another. The sender approves each transfer with their passkey.

Move money from one of your users' balances to another user's balance. You request the transfer, the sender approves it with their passkey, and the money lands in the recipient's balance, ready for their cards.

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/wallet_transfers \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rent-split-2026-11" \
  -d '{"from_user_id": "usr_9ae8d0b84fc1008ecb42b232", "to_user_id": "usr_41c07b2e9d5a6f3e8b1c0d27", "amount_cents": 2500, "description": "Rent split"}'
```

The response is a transfer in `pending_approval`, with an `approval_url`:

```json theme={null}
{
  "object": "wallet_transfer",
  "id": "wtr_5b2e8f0c1d7a4e93b6c2f018",
  "status": "pending_approval",
  "from_user_id": "usr_9ae8d0b84fc1008ecb42b232",
  "to_user_id": "usr_41c07b2e9d5a6f3e8b1c0d27",
  "amount_cents": 2500,
  "currency": "usd",
  "description": "Rent split",
  "approval_url": "https://vault.agentcard.sh/transfer?id=wtr_5b2e8f0c1d7a4e93b6c2f018",
  "expires_at": "2026-11-14T18:02:11.000Z",
  "decision": null,
  "tx_hash": null,
  "failure_code": null,
  "created_at": "2026-11-13T18:02:11.000Z",
  "completed_at": null
}
```

Send the `approval_url` to the sender. Nothing moves until they open it, see the amount and the recipient, and approve with their passkey. The sender has 24 hours; after that the request is `expired` and you request a new one. The sender can also decline, and the transfer reads `declined`.

Both people must be users of your company, connected with the same credential mode. A user of another company is refused as if they did not exist, and no transfer is made:

```json theme={null}
{
  "error": {
    "code": "connection_not_found",
    "message": "No production connection exists for that user. Sandbox and production users are separate: run the connect flow (POST /api/v2/connect/start) for this user with your production credentials first.",
    "docs": "https://docs.agentcard.com"
  }
}
```

A requested transfer holds its amount against the sender's balance until it completes, fails, expires or is declined. A second request the balance cannot cover is refused with `insufficient_funds`, and `available_cents` says what is left:

```json theme={null}
{
  "error": {
    "code": "insufficient_funds",
    "message": "The sender cannot send that much.",
    "docs": "https://docs.agentcard.com",
    "available_cents": 1000,
    "requested_cents": 2500
  }
}
```

A transfer counts against the [spend limits](https://docs.agentcard.com/api-reference/user-balance/overview.md) you set on the sender. A request the limits do not leave room for is refused with `wallet_spend_limit_exceeded`, and the error says which limit and how much is left:

```json theme={null}
{
  "error": {
    "code": "wallet_spend_limit_exceeded",
    "message": "This would pass the user's 24-hour wallet spend limit. 2000 cents are left of 10000.",
    "docs": "https://docs.agentcard.com",
    "limit": "daily",
    "limit_cents": 10000,
    "remaining_cents": 2000,
    "requested_cents": 2500
  }
}
```

A transfer starts counting when the sender approves it, not when you request it. Two requests can each fit the limit on their own and pass it together; the one approved second then ends `failed` with `wallet_spend_limit_exceeded`, and nothing moves. A transfer that ends `failed`, `declined` or `expired` stops counting.

## Follow a transfer

[Get the transfer](https://docs.agentcard.com/api-reference/wallet-transfers/get.md) to learn where it stands. The money starts moving the moment the sender approves, and usually lands within a minute. A read moves no money.

| Status | What it means | What to do next |
| - | - | - |
| `pending_approval` | Waiting for the sender. | Send them the `approval_url`. |
| `approved` | The sender approved; the money is about to move. | Read the transfer again. |
| `submitted` | The money is on its way. A transfer whose send Agentcard has to confirm by hand stays here until it does. | Read the transfer again. |
| `completed` | The money is in the recipient's balance. | Nothing. `tx_hash` names the Base transaction. |
| `declined` | The sender said no. | Ask the sender before requesting again. |
| `expired` | The sender did not answer within 24 hours. | Request a new transfer. |
| `failed` | The transfer ended without moving money. | Read `failure_code`. |

A transfer's `decision` records what the sender decided, when, with which method, and from which country when known:

```json theme={null}
"decision": {
  "type": "approved",
  "decided_at": "2026-11-13T18:04:52.000Z",
  "method": "passkey",
  "country": "US"
}
```

Keep it as your record of the sender's consent. Agentcard stores the IP address and browser of the request the sender decided from, and the API does not return them.

| `failure_code` | What it means | What to do next |
| - | - | - |
| `insufficient_funds` | The sender spent the money before the transfer could move it. | Request a smaller transfer. |
| `reverted` | The Base transaction failed, and nothing moved. | Request the transfer again. |
| `wallet_spend_limit_exceeded` | The sender approved, but a spend limit you set on them had no room left for it. Nothing moved. | Request it again once the 24-hour or 30-day window frees up, or raise the limit. |
| `wallet_policy_refused` | A spending limit on the sender's wallet refused it. | Request a smaller transfer, or raise the limit. |
| `order_credit_hold` | The sender's balance holds promotional credit that has to be spent on purchases. Nothing moved. | Request it again once the sender's orders have spent the credit. |
| `send_failed` | The transfer could not be sent within 23 hours of approval. | Request the transfer again. |

Transfers move real money, so they need a production credential. A sandbox credential is refused with `sandbox_not_supported`, on a read of a transfer as well as a request for one.


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