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

# Crypto wallets

> Create stablecoin wallets for your customers, check balances and send transfers.

Hyparrow lets you give each of your customers a **crypto wallet** for holding and
moving stablecoins across major networks. With one API key you can create
wallets, read balances, send external transfers and list transaction history —
all scoped to the customers belonging to your client account.

All endpoints below live under the base path `/api/v1` and are authenticated with
your API key credentials:

```
X-API-Key: <your-api-key>
X-API-Secret: <your-api-secret>
```

<Note>
  Base URL is `https://api.hyparrow.cloud/api/v1` in production. To test without
  moving real funds, point at the [Sandbox](/sandbox) —
  `https://sandbox.hyparrow.cloud/api/v1` — using a `pk_test_` key. Wallet
  creation, balances and transfers are all simulated there.
</Note>

## Supported networks and tokens

Wallets are created on one of these **networks** (case-insensitive):

| Network         | Value      |
| --------------- | ---------- |
| Base            | `BASE`     |
| Polygon         | `POLYGON`  |
| Ethereum        | `ETHEREUM` |
| Optimism        | `OPTIMISM` |
| BNB Smart Chain | `BSC`      |
| Solana          | `SOLANA`   |
| Tron            | `TRON`     |
| Aptos           | `APTOS`    |

Transfers move **stablecoins**:

| Token    | Value  |
| -------- | ------ |
| USD Coin | `USDC` |
| Tether   | `USDT` |

<Warning>
  **Transfer amounts are denominated in USD** (the dollar value of the
  stablecoin), sent as a string — for example `"25.00"` to send 25 USDC. The
  crypto network handles the on-chain mechanics.
</Warning>

## Create a wallet, check balance and transfer

<Steps>
  <Step title="Create a wallet for a customer">
    `POST /crypto/wallets` with the `customerId` (a UUID of one of your
    customers), the `network`, and an optional `label`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.hyparrow.cloud/api/v1/crypto/wallets \
        -H "X-API-Key: <your-api-key>" \
        -H "X-API-Secret: <your-api-secret>" \
        -H "Content-Type: application/json" \
        -d '{
          "customerId": "9d8e7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
          "network": "BASE",
          "label": "Main USDC wallet"
        }'
      ```

      ```json Body theme={null}
      {
        "customerId": "9d8e7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
        "network": "BASE",
        "label": "Main USDC wallet"
      }
      ```
    </CodeGroup>

    A `201 Created` returns the new wallet, including its `id` (the `walletId`
    you'll use everywhere else) and on-chain `walletAddress`:

    ```json Response theme={null}
    {
      "success": true,
      "message": "Crypto wallet created successfully",
      "data": {
        "wallet": {
          "id": "4b2f1a0e-7c6d-4e3f-9a8b-1c2d3e4f5a6b",
          "userId": "9d8e7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
          "walletAddress": "0x9aF3c1b2D4e5F6a7B8c9D0e1F2a3B4c5D6e7F8a9",
          "network": "BASE",
          "status": "active",
          "label": "Main USDC wallet"
        }
      }
    }
    ```
  </Step>

  <Step title="Check the balance">
    `GET /crypto/wallets/{walletId}/balance` returns the on-chain balances for
    the wallet.

    ```bash cURL theme={null}
    curl https://api.hyparrow.cloud/api/v1/crypto/wallets/4b2f1a0e-7c6d-4e3f-9a8b-1c2d3e4f5a6b/balance \
      -H "X-API-Key: <your-api-key>" \
      -H "X-API-Secret: <your-api-secret>"
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "walletId": "4b2f1a0e-7c6d-4e3f-9a8b-1c2d3e4f5a6b",
        "balances": [
          { "token": "USDC", "amount": "150.00" },
          { "token": "USDT", "amount": "0.00" }
        ]
      }
    }
    ```

    To list every wallet for a customer, use
    `GET /crypto/customers/{customerId}/wallets`.
  </Step>

  <Step title="Send a transfer">
    `POST /crypto/transfer` to move tokens out of a wallet to an external
    address. Specify the `walletId`, the `amount` in **USD**, the `asset` token
    and the `destination` address.

    ```bash cURL theme={null}
    curl https://api.hyparrow.cloud/api/v1/crypto/transfer \
      -H "X-API-Key: <your-api-key>" \
      -H "X-API-Secret: <your-api-secret>" \
      -H "Content-Type: application/json" \
      -d '{
        "walletId": "4b2f1a0e-7c6d-4e3f-9a8b-1c2d3e4f5a6b",
        "amount": "25.00",
        "asset": "USDC",
        "destination": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "message": "Transfer initiated successfully",
      "data": {
        "transfer": {
          "id": "tx_7f8e9d0c1b2a",
          "status": "pending",
          "token": "USDC",
          "toAddress": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b",
          "txHash": "0xabc123..."
        },
        "transaction": {
          "amount": "25.00",
          "asset": "USDC",
          "status": "pending",
          "network": "BASE",
          "transactionHash": "0xabc123..."
        }
      }
    }
    ```

    A transfer is typically `pending` at first while it confirms on-chain. Track
    it with the transactions endpoint below.
  </Step>

  <Step title="List wallet transactions">
    `GET /crypto/wallets/{walletId}/transactions` returns the wallet's
    transaction history, newest first.

    ```bash cURL theme={null}
    curl https://api.hyparrow.cloud/api/v1/crypto/wallets/4b2f1a0e-7c6d-4e3f-9a8b-1c2d3e4f5a6b/transactions \
      -H "X-API-Key: <your-api-key>" \
      -H "X-API-Secret: <your-api-secret>"
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "transactions": [
          {
            "type": "withdraw",
            "amount": "25.00",
            "asset": "USDC",
            "status": "pending",
            "toAddress": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b",
            "transactionHash": "0xabc123..."
          }
        ],
        "count": 1
      }
    }
    ```
  </Step>
</Steps>

## Edge cases

<AccordionGroup>
  <Accordion title="Unsupported network or token">
    Creating a wallet on a network outside the table above returns
    `400 Bad Request` with the list of supported networks. Likewise a transfer
    with an `asset` other than `USDC` or `USDT` returns `400 Bad Request`.
  </Accordion>

  <Accordion title="Customer not found">
    `customerId` must reference a customer that belongs to your client account.
    An unknown or non-owned customer returns `404 Not Found`.
  </Accordion>

  <Accordion title="Wallet access denied">
    Balance, transfer and transaction calls verify the wallet belongs to one of
    your customers. A wallet outside your account returns `403 Forbidden`.
  </Accordion>

  <Accordion title="Pending transfers">
    A transfer's `status` starts as `pending` and settles once confirmed on the
    crypto network. Poll
    `GET /crypto/wallets/{walletId}/transactions` to follow it to completion.
  </Accordion>
</AccordionGroup>

## Testing in the sandbox

In the [Sandbox](/sandbox), wallet creation, balances and transfers are all
simulated — no real chain calls and no real funds. Use a `pk_test_` key against
`https://sandbox.hyparrow.cloud/api/v1`. As with other payment flows, a transfer
amount ending in `.01` simulates a `failed` result and `.99` simulates a
`pending` one, so you can exercise both paths deterministically.