Crypto wallets

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>

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

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`

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.

Create a wallet, check balance and transfer

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.

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"
  }'

{
  "customerId": "9d8e7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
  "network": "BASE",
  "label": "Main USDC wallet"
}

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

Response

{
  "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"
    }
  }
}

Check the balance

GET /crypto/wallets/{walletId}/balance returns the on-chain balances for the wallet.

cURL

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>"

Response

{
  "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.

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.

cURL

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"
  }'

Response

{
  "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.

List wallet transactions

GET /crypto/wallets/{walletId}/transactions returns the wallet’s transaction history, newest first.

cURL

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>"

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "type": "withdraw",
        "amount": "25.00",
        "asset": "USDC",
        "status": "pending",
        "toAddress": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b",
        "transactionHash": "0xabc123..."
      }
    ],
    "count": 1
  }
}

Edge cases

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.

Customer not found

customerId must reference a customer that belongs to your client account. An unknown or non-owned customer returns 404 Not Found.

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.

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.

Testing in the sandbox

In the 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.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Supported networks and tokens

Create a wallet, check balance and transfer

Edge cases

Testing in the sandbox

​Supported networks and tokens

​Create a wallet, check balance and transfer

​Edge cases

​Testing in the sandbox

Supported networks and tokens

Create a wallet, check balance and transfer

Edge cases

Testing in the sandbox