Wallet Swap
Convert BRLA to USDC (or USDC to BRLA) from your Hodle wallet and deliver the result to any address on Polygon or Base.
POST /api/wallet/swap
Converts BRLA to USDC, or USDC to BRLA, out of the API key user's wallet. The converted asset is delivered on-chain to address (your own wallet when omitted) on destinationNetwork. Gas is paid by Hodle.
This route is enabled per account; ask support. Accounts without it use their standard swap behavior.
Funding completes before POST returns; conversion and delivery usually take another 20–60 seconds. Poll GET /api/wallet/swap/:swapId for the result. Every swap requires the wallet's PIN and protected key.
Funding uses Polygon first, then Base, choosing a network that holds the whole amount.
Fees
The fee comes out of the origin amount at funding. Conversion and delivery costs reduce the amount received. Fixed costs can consume a large share of small swaps; check the quote first.
GET /api/wallet/swap/quote
Returns an indicative price without a PIN or debit. The final amount can differ because the conversion is priced again when it runs.
| Query param | Required | Description |
|---|---|---|
fromAsset | yes | BRLA or USDC. |
toAsset | yes | USDC or BRLA. |
amount | yes | Gross amount in units of fromAsset, at most 10000. |
destinationNetwork | no | polygon (default) or base. |
subAccountId | no | Quote for a subaccount's wallet. |
curl --url "https://api.hodle.com.br/api/wallet/swap/quote?fromAsset=USDC&toAsset=BRLA&amount=100&destinationNetwork=base" \
--header "Authorization: Bearer $API_KEY"{
"success": true,
"fromAsset": "USDC",
"toAsset": "BRLA",
"amount": "100",
"destinationNetwork": "base",
"fee": { "bps": 70, "amount": "0.7", "asset": "USDC" },
"conversion": {
"amountIn": "99.30",
"rate": 4.986155,
"cost": "2.185784",
"costAsset": "USDC"
},
"amountOut": "484.226000",
"amountOutAsset": "BRLA"
}fee: what is taken fromamountat funding, in units offee.asset.conversion.amountIn: what is converted after the fee.conversion.rate: base rate in BRLA per USDC, for both directions.conversion.cost: the conversion's own costs, incostAsset, already discounted fromamountOut.amountOut: whataddresswould receive, inamountOutAsset.
Request
| Field | Type | Required | Description |
|---|---|---|---|
fromAsset | "BRLA" | "USDC" | yes | Asset debited from your wallet. |
toAsset | "USDC" | "BRLA" | yes | Asset delivered. |
amount | string | yes | Gross amount in units of fromAsset (e.g. "100", "12.5"), at most 10000. The fee comes out of it. |
walletPin | string | yes | Wallet PIN. |
protectedSymmetricKey | string | yes | The wallet's protected symmetric key. |
address | string | no | EVM address that receives toAsset. Defaults to your own wallet. |
destinationNetwork | "polygon" | "base" | no | Network where toAsset is delivered. Defaults to polygon. |
subAccountId | string | no | Swap out of a subaccount's wallet instead of the main account's. |
reference | string | no | Your own reference, stored with the swap. |
clientRequestId | string | no | Idempotency key scoped to the API key owner; 1–100 letters, digits, underscores or hyphens. |
An identical retry with the same clientRequestId returns the saved swap without another funding attempt. Until its funding leg is confirmed, the retry returns 409 IDEMPOTENCY_IN_PROGRESS with success: false and the saved swapId and status. Once funding is confirmed, the retry returns success. Reusing the key with a different wallet scope, asset pair, amount, destination, network or reference returns 409 IDEMPOTENCY_CONFLICT.
Once a swap intent is created, its key remains consumed even if funding fails or cannot be confirmed. Replaying a FAILED swap returns HTTP 502 with success: false and the saved swapId and status. A new funding attempt requires a new key; confirm the previous funding outcome with support before retrying an uncertain transfer.
curl --request POST \
--url https://api.hodle.com.br/api/wallet/swap \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"fromAsset": "BRLA",
"toAsset": "USDC",
"amount": "100",
"walletPin": "424242",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
"address": "0x9b8c4d5e6f7081234567890abcdef0123456789a",
"destinationNetwork": "polygon",
"reference": "order-1029"
}'const res = await fetch('https://api.hodle.com.br/api/wallet/swap', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
fromAsset: 'BRLA',
toAsset: 'USDC',
amount: '100',
walletPin: '424242',
protectedSymmetricKey: 'AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...',
address: '0x9b8c4d5e6f7081234567890abcdef0123456789a',
destinationNetwork: 'polygon',
}),
})
const swap = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/wallet/swap",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
json={
"fromAsset": "BRLA",
"toAsset": "USDC",
"amount": "100",
"walletPin": "424242",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
"address": "0x9b8c4d5e6f7081234567890abcdef0123456789a",
"destinationNetwork": "polygon",
},
)
swap = res.json()Response
{
"success": true,
"swapId": "a75fb23f-195c-4c23-aeb6-a9543dfd64bd",
"status": "RUNNING",
"destinationAddress": "0x9b8C4D5E6F7081234567890abCDef0123456789a",
"destinationNetwork": "polygon",
"fee": { "bps": 70, "amount": "700000000000000000", "asset": "BRLA" },
"legs": [
{
"index": 0,
"fromAsset": "BRLA",
"toAsset": "BRLA",
"status": "FULFILLED",
"originTxHash": "0xa2dfcb8ae6c9ad71ed8ce088f094d3ec62834ee927d7a2587de8fa0325e9c538",
"destinationTxHash": null
},
{
"index": 1,
"fromAsset": "BRLA",
"toAsset": "USDC",
"status": "PENDING",
"originTxHash": null,
"destinationTxHash": null
}
]
}fee.amount is in the smallest unit of fee.asset (18 decimals for BRLA, 6 for USDC). legs[0].originTxHash is the funding transaction.
GET /api/wallet/swap/:swapId
curl --url https://api.hodle.com.br/api/wallet/swap/a75fb23f-195c-4c23-aeb6-a9543dfd64bd \
--header "Authorization: Bearer $API_KEY"When the conversion is delivered, status is COMPLETED and legs[1].destinationTxHash is the delivery transaction on destinationNetwork.
status | Meaning |
|---|---|
RUNNING | Funding or conversion is in progress. Funding is confirmed only when legs[0].status is FULFILLED. Keep polling. |
COMPLETED | Delivered to address. |
FAILED | Funding failed or could not be confirmed. Contact support with swapId before retrying. |
STRANDED | Funded, but the conversion did not complete. The amount is held and reviewed by Hodle; contact support with the swapId. |
Errors
| Status | When |
|---|---|
400 | Invalid amount (quote: INVALID_AMOUNT; POST may return only error), unsupported pair (UNSUPPORTED_PAIR), insufficient funds on both Polygon and Base (INSUFFICIENT_BALANCE), invalid destination (INVALID_ADDRESS), or fee consumes the amount (AMOUNT_TOO_SMALL). |
401 | Missing or invalid API key. |
403 | Quote route not enabled (NOT_ENABLED). |
404 | Wallet, subaccount or swap not found within your account. |
409 | clientRequestId was already used for a different swap intent (IDEMPOTENCY_CONFLICT), or funding for the saved intent is still pending or unconfirmed (IDEMPOTENCY_IN_PROGRESS). For an in-progress intent, check the returned swapId and retry with the same key. |
502 | Quote unavailable (QUOTE_UNAVAILABLE), or funding failed or could not be confirmed (FUNDING_LEG_FAILED). Check the returned swapId and status. |
503 | Conversion account unavailable (STABLE_ACCOUNT_UNAVAILABLE), no funding destination (NO_DEPOSIT_WALLET), or service temporarily unavailable (HOUSE_WALLET_UNAVAILABLE). Retry later. |