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

## Endpoints

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

## Create a Wallet

```http theme={null}
POST /v2/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 /v2/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 /v2/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 /v2/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.

<Steps>
  <Step title="Create or retrieve a wallet">
    Use `POST /v2/wallets` or `GET /v2/wallets`, then store `walletId`,
    `walletAddress`, `symbol`, and `blockchain`.
  </Step>

  <Step title="Transfer the asset">
    Send funds to `walletAddress` from a wallet in the same environment and on
    the specified blockchain.
  </Step>

  <Step title="Wait for confirmation">
    ON RAMP automatically records the deposit after confirmation and sends the
    result through a `deposit_crypto` webhook.
  </Step>

  <Step title="Retrieve the balance">
    Check the updated balance with `GET /v2/wallets/{id}/balance`.
  </Step>
</Steps>

<Warning>
  Confirm whether you are using testnet or mainnet before transferring funds. Do
  not send real funds to a test address.
</Warning>

See the notification contract under [crypto transaction webhooks](/en/webhooks#crypto-transaction-payloads).