Wallets

Overview

A wallet is an on-chain address managed through the Honeycoin API. Your application does not need to handle private keys directly. You create a wallet for a supported chain, show the returned address to your user or counterparty, and use wallet transactions and webhooks to track activity.

1. Create a Wallet Address

Create a wallet address for the chain you want to receive funds on.

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

{
  "success": true,
  "data": {
    "id": "wallet_123",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  }
}

Store the returned id as your walletId. You will use it to fetch balances, send funds, subscribe to webhooks, and reconcile transactions.

2. Retrieve Wallets and Balances

Use the wallet address endpoints to list wallets or retrieve a specific wallet.

curl --request GET   
--url [https://crypto.honeycoin.app/api/wallets/addresses/wallet_123](https://crypto.honeycoin.app/api/wallets/addresses/wallet_123)   
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' The response includes the wallet address, chain, balances when available, and creation time.

3. Send Funds From a Wallet

To send funds, provide the source walletId, destination address, token, amount, and chain.

curl --request POST \
  --url https://crypto.honeycoin.app/api/wallets/transactions/transfer \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "walletId": "wallet_123",
    "to": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "amount": 10,
    "token": "USDC",
    "chain": "base"
  }'

{
  "success": true,
  "data": {
    "transactionId": "tx_123",
    "transactionHash": "0xabc123..."
  }
}

Use transactionId for Honeycoin API reconciliation and transactionHash for on-chain confirmation.

4. Track Wallet Transactions

After creating or sending transactions, retrieve wallet transaction history:

curl --request GET   
--url '[https://crypto.honeycoin.app/api/wallets/transactions?walletId=wallet_123&limit=20](https://crypto.honeycoin.app/api/wallets/transactions?walletId=wallet_123\&limit=20)'   
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' You can also retrieve a single transaction by ID and include on-chain details when needed:

You can also retrieve a single transaction by ID and include on-chain details when needed:

GET /wallets/transactions/{transactionId}?includeOnchain=true

5. Subscribe to Wallet Webhooks

Create a subscription to receive wallet transaction events at your webhook URL.

curl --request POST \
  --url https://crypto.honeycoin.app/api/wallets/subscriptions \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "walletId": "wallet_123",
    "chain": "base",
    "webhookUrl": "https://example.com/webhooks/honeycoin"
  }'

Wallet webhook events are sent as wallet.transaction.received and include the wallet ID, subscription ID, chain, address, transaction hash, amount, sender, recipient, and token details.

6. Handle Webhook Delivery

Your webhook endpoint should return a 2xx response quickly after receiving the event. If processing takes longer, store the event and process it asynchronously.

You can inspect webhook deliveries with:

GET /wallets/webhooks?walletId=wallet_123

If a delivery fails, you can resend it:

POST /wallets/webhooks/{webhookId}/resend

Best Practices

• Store walletId, address, chain, and your internal customer or order reference together.
• Treat webhook events as the source for real-time updates, but use transaction lookup for final reconciliation.
• Make your webhook handler idempotent by storing processed webhook IDs.
• Always verify the chain and token before showing an address or initiating a transfer.
• Keep bearer tokens server-side and refresh them before expiration.
• Monitor failed webhook deliveries and resend them after fixing your endpoint.