Wallet Transfer

Move USDT/USDC between Hodle wallets or to any external address. Gas is sponsored.

POST /api/wallet/transfer

Transfers stablecoin from the API key user's wallet to either another linked user or an external EVM address. Gas is paid by Hodle — the user does not need MATIC or ETH.

The API key user is the source. Pass either toUserId (a user previously created via POST /api/user/create) or recipientAddress for an external transfer.

Request

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/transfer \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "toUserId": "65f1a83b6b7c2b001f3c9e21",
    "amount": "5.00",
    "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',
  }),
})
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",
    },
)
data = res.json()

Parameters

Field	Type	Required	Description
`toUserId`	string	Yes (or `recipientAddress`)	Hodle userId of the recipient. Must be linked to your platform.
`recipientAddress`	string	Yes (or `toUserId`)	EVM address (`0x...`). Use this for external transfers.
`amount`	string	Yes	Amount in the wallet's stablecoin (USDT/USDC), as a decimal string.
`reference`	string	No	Free-form note stored on the transaction record for your reconciliation.

Provide exactly one of toUserId or recipientAddress.

Response

200 OK

{
  "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).

Errors

400 — both or neither recipient given

{ "success": false, "error": "Provide toUserId or recipientAddress" }

400 — recipient could not be resolved

{ "success": false, "error": "Recipient address could not be resolved" }

400 — insufficient balance

{ "success": false, "error": "ERC20: transfer amount exceeds balance" }

401 — missing or invalid API key

{ "success": false, "error": "Unauthorized" }

When to use this vs. `wallet/payout`

/api/wallet/transfer moves stablecoin on-chain. The recipient ends up holding USDT/USDC.
/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.