Wallet Transfer

Move USDT, USDC, BRLA or BRS from a Hodle wallet to a subaccount or any external address on Polygon, Base, Solana or BNB Chain. Gas is sponsored.

POST /api/wallet/transfer

Sends stablecoin from one of your wallets to a subaccount under your platform or to any external address. Network fees are sponsored: the wallet needs no MATIC, ETH, BNB or SOL.

NetworkAssets
polygonUSDT, USDC, BRLA
baseUSDC, BRLA, BRS
solanaUSDT, USDC, BRS
bnbUSDT

network defaults to polygon and asset to USDT. BNB Chain and BRS are enabled per account (ask support).

Every transfer is signed with the source wallet's walletPin and protectedSymmetricKey. Hodle never stores them, so your platform keeps each subaccount's PIN and sends it on every request. See Wallet Keys.

To send from a subaccount wallet, pass its fromSubAccountId together with the source walletId, walletPin and protectedSymmetricKey. Omitting fromSubAccountId selects your main account's wallets, even when you supply a subaccount's walletId. toSubAccountId selects the recipient.

Request

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/transfer \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "toSubAccountId": "5b9f1a83b6b7c2b001f3c9e21",
    "amount": "5.00",
    "walletPin": "424242",
    "protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
    "reference": "internal-payroll-#1029"
  }'
const res = await fetch('https://api.hodle.com.br/api/wallet/transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipientAddress: '0x9b8c4d5e6f7081234567890abcdef0123456789a',
    amount: '12.50',
    walletPin: '424242',
    protectedSymmetricKey: 'AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...',
  }),
})
const data = await res.json()
import os, requests

res = requests.post(
    "https://api.hodle.com.br/api/wallet/transfer",
    headers={
        "Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "recipientAddress": "0x9b8c4d5e6f7081234567890abcdef0123456789a",
        "amount": "12.50",
        "walletPin": "424242",
        "protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
    },
)
data = res.json()

Parameters

FieldTypeRequiredDescription
fromSubAccountIdstringNoSource subaccount to debit. Defaults to your main account when omitted.
toSubAccountIdstringYes (or recipientAddress)Recipient subaccount under your platform.
networkstringNopolygon (default), base, solana or bnb.
assetstringNoToken to move. Defaults to USDT.
recipientAddressstringYes (or toSubAccountId)External address: 0x... on EVM networks, base58 on solana.
amountstringYesAmount of asset to send, as a decimal string. Max 10000.
walletIdstringNoSource wallet (data.id from /api/wallet/create). Omit to use the default wallet.
walletPinstringYesThe source wallet's PIN.
protectedSymmetricKeystringYesThe source wallet's protectedSymmetricKey.
referencestringNoYour reconciliation id. A retry with the same value returns 409 instead of sending twice.

Provide exactly one of toSubAccountId or recipientAddress.

Response

200 OK
{
  "success": true,
  "data": {
    "txHash": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
    "recipientAddress": "0x9b8c4d5e6f7081234567890abcdef0123456789a",
    "amount": "12.50"
  }
}
FieldTypeDescription
data.txHashstringHash of the on-chain transfer. Look it up on the explorer.
data.recipientAddressstringThe address that received the funds.
data.amountstringAmount transferred (echoes the request).

The response can be 202 with data.status: "PENDING": the transfer was submitted but its confirmation was not seen in time. Do not send it again. On BNB Chain data.txHash is null and data.userOpHash identifies the submission; on Solana data.txHash is the broadcast signature, which you can check on-chain. A retry with the same reference returns 409 with the stored state. On Solana the transfer then moves to COMPLETED once finalized, or to FAILED if it never landed (nothing moved; send again with a new reference).

Getting notified when the transfer settles

Instead of polling, subscribe to WALLET_TRANSFER_COMPLETED and WALLET_TRANSFER_FAILED in API Keys → Webhooks. Every transfer that returns a transactionId sends exactly one of them when it reaches a final on-chain state, to any destination, from your account or any sub-account: a 200 sends WALLET_TRANSFER_COMPLETED right away, a 202 sends it once confirmed, or WALLET_TRANSFER_FAILED if it never landed. Match the event to the request by transactionId or reference.

Errors

StatusWhen
400Both or neither of toSubAccountId / recipientAddress, unresolvable recipient, asset not supported on the network, insufficient balance, wrong walletPin / protectedSymmetricKey or BNB Chain amount below 1 USDT (BNB_AMOUNT_BELOW_MINIMUM).
401Missing or invalid API key.
403BNB Chain or BRS not enabled, or the account is not approved for production (BNB_FEATURE_DISABLED, BNB_PLANE_NOT_ACTIVE, BRS_BASE_PRODUCTION_ONLY).
409A transfer with the same reference already exists (the body carries its transactionId, status and txHash), or, without a reference, another transfer from the same account is still running (TRANSFER_IN_PROGRESS).
400
{ "success": false, "error": "Provide toSubAccountId or recipientAddress" }

When to use this vs. wallet/payout

  • /api/wallet/transfer moves stablecoin on-chain. The recipient ends up holding the token you sent.
  • /api/wallet/payout moves stablecoin out of the wallet and settles the receiver in BRL via PIX. Use it when the recipient is a Brazilian PIX key.