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.

To exercise the complete lifecycle without moving real funds, follow the Testing Wallets guide.

When To Use This

Use Wallets when you need managed on-chain addresses for receiving funds, sending supported tokens, tracking wallet transactions, and receiving wallet-specific webhooks.

Happy Path

1. Create a wallet address for the chain you want to support.

2. Store the returned walletId, address, and chain with your customer or order record.

3. Show the address to the sender or initiate a transfer from the wallet.

4. Track wallet transactions through API lookups and webhook events.

5. Reconcile final status using Honeycoin transaction IDs and on-chain transaction hashes.

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

Network Fee Sponsorship

Honeycoin automatically sponsors the network fee when the source wallet supports sponsored transfers. Sponsorship is available for wallets on ETH, ARB, BASE, MATIC, BSC, OPTIMISM, SOLANA, and TEMPO. Wallet transfers on TRON are not sponsored and follow the network's standard fee requirements.

Sponsorship is determined from the source wallet's stored capability. Do not include a sponsored field in the request. See Supported Blockchains & Features for the complete matrix.

{
  "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' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

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.
• Do not add a sponsored field to wallet transfer requests. Honeycoin determines fee sponsorship from the source wallet.
• Keep bearer tokens server-side and refresh them before expiration.
• Monitor failed webhook deliveries and resend them after fixing your endpoint.