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 paramRequiredDescription
fromAssetyesBRLA or USDC.
toAssetyesUSDC or BRLA.
amountyesGross amount in units of fromAsset, at most 10000.
destinationNetworknopolygon (default) or base.
subAccountIdnoQuote 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 from amount at funding, in units of fee.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, in costAsset, already discounted from amountOut.
  • amountOut: what address would receive, in amountOutAsset.

Request

FieldTypeRequiredDescription
fromAsset"BRLA" | "USDC"yesAsset debited from your wallet.
toAsset"USDC" | "BRLA"yesAsset delivered.
amountstringyesGross amount in units of fromAsset (e.g. "100", "12.5"), at most 10000. The fee comes out of it.
walletPinstringyesWallet PIN.
protectedSymmetricKeystringyesThe wallet's protected symmetric key.
addressstringnoEVM address that receives toAsset. Defaults to your own wallet.
destinationNetwork"polygon" | "base"noNetwork where toAsset is delivered. Defaults to polygon.
subAccountIdstringnoSwap out of a subaccount's wallet instead of the main account's.
referencestringnoYour own reference, stored with the swap.
clientRequestIdstringnoIdempotency 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.

statusMeaning
RUNNINGFunding or conversion is in progress. Funding is confirmed only when legs[0].status is FULFILLED. Keep polling.
COMPLETEDDelivered to address.
FAILEDFunding failed or could not be confirmed. Contact support with swapId before retrying.
STRANDEDFunded, but the conversion did not complete. The amount is held and reviewed by Hodle; contact support with the swapId.

Errors

StatusWhen
400Invalid 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).
401Missing or invalid API key.
403Quote route not enabled (NOT_ENABLED).
404Wallet, subaccount or swap not found within your account.
409clientRequestId 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.
502Quote unavailable (QUOTE_UNAVAILABLE), or funding failed or could not be confirmed (FUNDING_LEG_FAILED). Check the returned swapId and status.
503Conversion account unavailable (STABLE_ACCOUNT_UNAVAILABLE), no funding destination (NO_DEPOSIT_WALLET), or service temporarily unavailable (HOUSE_WALLET_UNAVAILABLE). Retry later.