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