Testing Wallets

Overview

The Wallets sandbox lets you create wallets, simulate incoming funds, send simulated transfers, receive real HTTP webhook deliveries, inspect transactions, and clear your test state. Sandbox balances and transactions are isolated from production, and no request in this guide moves real funds or broadcasts an on-chain transaction.

The Wallets sandbox base URL is:

https://crypto.honeycoin.app/api/sandbox

All Wallets sandbox requests require a sandbox bearer token:

Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN

Your Honeycoin account must also have Wallets enabled. Contact Honeycoin support if the API returns Kindly contact support to enable wallets for your account.

Before You Begin

You need:

• Your sandbox API key and public key.
• An HTTPS webhook URL that can receive POST requests and return a 2xx response within 10 seconds.
• A supported wallet chain and token. The examples below use BASE and USDC.

Generate a sandbox bearer token with your sandbox credentials:

curl --request POST \
  --url https://api-v2.honeycoin.app/api/sandbox/b2b/auth/generate-bearer-token \
  --header 'api-key: YOUR_SANDBOX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "publicKey": "YOUR_PUBLIC_KEY"
  }'

Use the returned token in every request below. Sandbox bearer tokens cannot be used with the production Wallets base URL.

1. Create a Wallet

curl --request POST \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/addresses \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "BASE"
  }'

The response contains the values you will use throughout the test:

{
  "success": true,
  "data": {
    "id": "YOUR_WALLET_ID",
    "address": "0x..."
  }
}

Store data.id as the walletId. The returned address is generated for the sandbox and must not receive real crypto.

2. Subscribe to Wallet Webhooks

Create the subscription before simulating a transaction so the event can produce a webhook delivery.

curl --request POST \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/subscriptions \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "walletId": "YOUR_WALLET_ID",
    "chain": "BASE",
    "webhookUrl": "https://your-domain.example/webhooks/honeycoin",
    "expiryInMinutes": 120
  }'

webhookUrl must use HTTPS. expiryInMinutes is optional and cannot exceed 120 minutes. Store the returned subscriptionId so you can filter webhook delivery records later.

3. Simulate an Incoming Transfer

The sandbox-only events endpoint represents a detected chain event. For transfer.in, provide the external sender in from; the wallet address is selected from walletId automatically.

curl --request POST \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/events \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "transfer.in",
    "transactionHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "walletId": "YOUR_WALLET_ID",
    "amount": "25.00",
    "token": "USDC",
    "chain": "BASE",
    "from": "0x2222222222222222222222222222222222222222"
  }'

A successful request:

• Adds 25.00 USDC to the wallet's sandbox balance.
• Creates a successful deposit transaction.
• Queues a wallet.transaction.received webhook for each matching active subscription.
• Returns transactionId, transactionHash, direction, isNew, and webhookQueued.

Use a unique transactionHash for each new simulated chain event. Reusing the same hash for the same wallet, chain, and token is treated as a replay and does not credit the balance twice.

4. Verify the Balance and Transaction

Retrieve the wallet to confirm its balances:

curl --request GET \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/addresses/YOUR_WALLET_ID \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

Retrieve the transaction using the transactionId returned by the simulated event:

curl --request GET \
  --url 'https://crypto.honeycoin.app/api/sandbox/wallets/transactions/YOUR_TRANSACTION_ID?includeOnchain=true' \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

The transaction is marked successful. When includeOnchain=true, the response also includes simulated on-chain details with provider: sandbox and a zero fee.

5. Test an Outgoing Transfer

An outgoing transfer deducts the token from the sandbox balance created in step 3. The sandbox validates the destination address and rejects an amount greater than the available balance.

curl --request POST \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/transactions/transfer \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "walletId": "YOUR_WALLET_ID",
    "to": "0x000000000000000000000000000000000000dEaD",
    "amount": "5.00",
    "token": "USDC",
    "chain": "BASE"
  }'

The response contains a sandbox-generated transactionId and transactionHash. The transfer is recorded as successful immediately, the balance is reduced, and matching subscriptions receive a wallet.transaction.sent webhook. No transaction is broadcast to Base.

To test an insufficient-funds response, repeat the request with an amount greater than the current sandbox balance. The expected error code is INSUFFICIENT_FUNDS, and the balance is unchanged.

6. Inspect and Resend Webhooks

Webhook fanout and delivery are asynchronous. Poll the deliveries endpoint after creating an event or transfer:

curl --request GET \
  --url 'https://crypto.honeycoin.app/api/sandbox/wallets/webhooks?walletId=YOUR_WALLET_ID&limit=20' \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

Retrieve one delivery to inspect the exact payload, request headers, response, and attempt log:

curl --request GET \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/webhooks/YOUR_WEBHOOK_ID \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

Sandbox wallet webhooks include these identifying headers:

• x-hc-webhook-source: sandbox
• x-hc-webhook-type
• x-hc-webhook-id
• x-hc-subscription-id
• x-hc-wallet-id
• x-hc-blockchain-hook-id

The request body uses this structure:

{
  "id": "YOUR_WEBHOOK_ID",
  "eventId": "YOUR_EVENT_ID",
  "type": "wallet.transaction.received",
  "walletId": "YOUR_WALLET_ID",
  "subscriptionId": "YOUR_SUBSCRIPTION_ID",
  "address": "0x...",
  "chain": "BASE",
  "direction": "in",
  "transaction": {
    "txId": "0x...",
    "blockNumber": "...",
    "from": "0x...",
    "to": "0x...",
    "direction": "in",
    "amount": "25.0",
    "timestamp": "2026-07-13T12:00:00.000Z",
    "token": {
      "symbol": "USDC",
      "decimals": 6,
      "contractAddress": "0x..."
    }
  }
}

After fixing a webhook receiver, queue a delivery again:

curl --request POST \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/webhooks/YOUR_WEBHOOK_ID/resend \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

Make your receiver idempotent: a resend delivers the same webhook ID and payload again.

7. Reset Sandbox Wallet State

Use the reset endpoint when you need a clean test account:

curl --request DELETE \
  --url https://crypto.honeycoin.app/api/sandbox/wallets/state \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

This permanently deletes all sandbox wallets, balances, events, transactions, subscriptions, and webhook delivery records owned by the authenticated account. It does not affect production data.

Recommended Test Scenarios

Endpoint Summary