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

# Wallet

> Create, manage, and query digital wallets.

The Wallet module creates wallets, adds blockchain assets, and retrieves available balances for the authenticated business.

Wallet endpoints in v3 use the same parameters and responses as v2. Send the JWT obtained from `POST /v3/auth/login` in the `Authorization: Bearer {accessToken}` header. See [Authentication](https://docs.mesadepagos.com/en/v3/auth.md) to obtain a token.

## Endpoints

| Name | Method | Path |
| - | - | - |
| Create wallet | `POST` | `/v3/wallets` |
| List wallets | `GET` | `/v3/wallets` |
| Add asset to wallet | `POST` | `/v3/wallets/{id}/assets` |
| Retrieve wallet balance | `GET` | `/v3/wallets/{id}/balance` |

## Create a Wallet

```http theme={null}
POST /v3/wallets
```

The initial asset depends on the environment:

| Environment | Initial asset |
| - | - |
| Sandbox | `USDC/Ethereum` |
| Production | `USDC/Polygon` |

The following example applies to Sandbox.

```json theme={null}
{
  "walletName": "main_wallet"
}
```

### Response

```json theme={null}
{
  "walletId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "createdAt": "2026-05-12T12:00:00.000Z",
  "assets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "walletAddress": "0x0000000000000000000000000000000000000000",
      "legacyAddress": null,
      "symbol": "USDC",
      "blockchain": "Ethereum"
    }
  ]
}
```

Assets in previously created wallets do not change. Before transferring funds, always use the blockchain returned by the API.

## List Wallets

```http theme={null}
GET /v3/wallets
```

### Response

The following example shows a wallet created in Sandbox. In Production, the initial asset uses `Polygon`.

```json theme={null}
{
  "wallets": [
    {
      "walletId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "ACTIVE",
      "createdAt": "2026-05-12T12:00:00.000Z",
      "assets": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "walletAddress": "0x0000000000000000000000000000000000000000",
          "legacyAddress": null,
          "symbol": "USDC",
          "blockchain": "Ethereum"
        }
      ]
    }
  ]
}
```

## Add an Asset to a Wallet

```http theme={null}
POST /v3/wallets/{id}/assets
```

```json theme={null}
{
  "symbol": "USDC",
  "blockchain": "Polygon"
}
```

### Response

```json theme={null}
{
  "walletId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "createdAt": "2026-05-12T12:00:00.000Z",
  "assets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "walletAddress": "0x0000000000000000000000000000000000000000",
      "legacyAddress": null,
      "symbol": "USDC",
      "blockchain": "Polygon"
    }
  ]
}
```

## Retrieve a Wallet Balance

```http theme={null}
GET /v3/wallets/{id}/balance
```

### Query Parameters

| Parameter | Required | Description |
| - | - | - |
| `symbol` | No | Asset used to filter the balance. |
| `blockchain` | No | Blockchain used to filter balance. |

### Response

```json theme={null}
{
  "walletId": "550e8400-e29b-41d4-a716-446655440001",
  "balances": [
    {
      "assetId": "550e8400-e29b-41d4-a716-446655440000",
      "symbol": "USDC",
      "blockchain": "Polygon",
      "walletAddress": "0x0000000000000000000000000000000000000000",
      "balance": 100.5
    }
  ]
}
```

## Crypto Deposits

Crypto deposits are sent directly to `walletAddress` using the asset and blockchain specified by the wallet.

**1. Create or retrieve a wallet**

Use `POST /v3/wallets` or `GET /v3/wallets`, then store `walletId`,
`walletAddress`, `symbol`, and `blockchain`.

**2. Transfer the asset**

Send funds to `walletAddress` from a wallet in the same environment and on
the specified blockchain.

**3. Wait for confirmation**

ON RAMP automatically records the deposit after confirmation and sends the
result through a `deposit_crypto` webhook.

**4. Retrieve the balance**

Check the updated balance with `GET /v3/wallets/{id}/balance`.

> [!WARNING]
>
> Confirm whether you are using testnet or mainnet before transferring funds. Do
> not send real funds to a test address.

See the notification contract under [crypto transaction webhooks](https://docs.mesadepagos.com/en/v3/webhooks.md#crypto-transaction-payloads).


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