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

# Wallet

> A connected user's balance, and how to fund it from your own UI.

The **wallet** is a connected user's Agentcard balance. It is provisioned on first read. To fund it you request a payment link (Apple Pay / Google Pay), show it in your UI, and poll the funding session until the money lands. Funding requires a phone verification fresh within 60 days; you relay that code through your UI the same way as the connect code.

## The wallet object

| Field                 | Type    | Description                                                                                                 |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `object`              | string  | `wallet`                                                                                                    |
| `user_id`             | string  |                                                                                                             |
| `address`             | string  | The wallet's on-chain address (USDC on Base).                                                               |
| `balance_usdc`        | string  | Current balance in USD, as a decimal string.                                                                |
| `balance_unavailable` | boolean | Present and true when the balance could not be read right now. Distinguish "no funds" from "couldn't read". |
| `status`              | string  |                                                                                                             |

```json theme={null}
{ "object": "wallet", "user_id": "usr_123", "address": "0xabc…", "balance_usdc": "25.00", "status": "active" }
```

## The funding session object

| Field                                      | Type           | Description                                                                                       |
| ------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------- |
| `id`, `user_id`                            | string         |                                                                                                   |
| `status`                                   | string         | `pending`, `processing`, `completed`, `failed`, `expired`.                                        |
| `amount_cents`, `currency`                 |                | What the wallet is credited.                                                                      |
| `payment_method`                           | string         | `apple_pay` or `google_pay`.                                                                      |
| `checkout_url`                             | string         | The payment link to show the user.                                                                |
| `link_type`                                | string         | `hosted` (openable for 30 minutes) or `embedded` (single use, \~5 minutes). Create response only. |
| `fee_cents`, `fees_covered`                |                | The provider fee and whether Agentcard absorbs it. Do not gross up the amount.                    |
| `failure_reason`                           | string or null | `region_not_supported`, `provider_error`.                                                         |
| `expires_at`, `completed_at`, `created_at` | string         |                                                                                                   |

## Endpoints

| Endpoint                               |                                                                                           |
| -------------------------------------- | ----------------------------------------------------------------------------------------- |
| `GET /api/v2/wallet`                   | [Get the user's wallet](/api-reference/wallet/get)                                        |
| `POST /api/v2/wallet/fund`             | [Create a funding session](/api-reference/wallet/fund): single use, expires in 30 minutes |
| `GET /api/v2/wallet/fund/{session_id}` | [Get a funding session](/api-reference/wallet/fund-status)                                |
| `POST /api/v2/wallet/phone/start`      | [Start phone verification](/api-reference/wallet/phone-start)                             |
| `POST /api/v2/wallet/phone/verify`     | [Verify the phone code](/api-reference/wallet/phone-verify)                               |