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.
| Network | Assets |
|---|---|
polygon | USDT, USDC, BRLA |
base | USDC, BRLA, BRS |
solana | USDT, USDC, BRS |
bnb | USDT |
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
| Field | Type | Required | Description |
|---|---|---|---|
fromSubAccountId | string | No | Source subaccount to debit. Defaults to your main account when omitted. |
toSubAccountId | string | Yes (or recipientAddress) | Recipient subaccount under your platform. |
network | string | No | polygon (default), base, solana or bnb. |
asset | string | No | Token to move. Defaults to USDT. |
recipientAddress | string | Yes (or toSubAccountId) | External address: 0x... on EVM networks, base58 on solana. |
amount | string | Yes | Amount of asset to send, as a decimal string. Max 10000. |
walletId | string | No | Source wallet (data.id from /api/wallet/create). Omit to use the default wallet. |
walletPin | string | Yes | The source wallet's PIN. |
protectedSymmetricKey | string | Yes | The source wallet's protectedSymmetricKey. |
reference | string | No | Your reconciliation id. A retry with the same value returns 409 instead of sending twice. |
Provide exactly one of toSubAccountId or recipientAddress.
Response
{
"success": true,
"data": {
"txHash": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
"recipientAddress": "0x9b8c4d5e6f7081234567890abcdef0123456789a",
"amount": "12.50"
}
}| Field | Type | Description |
|---|---|---|
data.txHash | string | Hash of the on-chain transfer. Look it up on the explorer. |
data.recipientAddress | string | The address that received the funds. |
data.amount | string | Amount 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
| Status | When |
|---|---|
400 | Both 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). |
401 | Missing or invalid API key. |
403 | BNB Chain or BRS not enabled, or the account is not approved for production (BNB_FEATURE_DISABLED, BNB_PLANE_NOT_ACTIVE, BRS_BASE_PRODUCTION_ONLY). |
409 | A 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). |
{ "success": false, "error": "Provide toSubAccountId or recipientAddress" }When to use this vs. wallet/payout
/api/wallet/transfermoves stablecoin on-chain. The recipient ends up holding the token you sent./api/wallet/payoutmoves stablecoin out of the wallet and settles the receiver in BRL via PIX. Use it when the recipient is a Brazilian PIX key.