Stellar (USDC)

Stellar is available for USDC. Each account (and each sub-account) gets its own Stellar wallet, ready to receive USDC the moment it is created: Hodle activates the account on-chain and opens its USDC trustline for you, and pays every network fee. Your users never need XLM.

Stellar is enabled per account. Ask your Hodle contact to enable it for your API key; until then network: "stellar" answers 403. Sandbox support (Stellar testnet, test USDC) is coming soon.

How it works

1. Create the wallet

The key is protected by the account's wallet PIN, like every other Hodle wallet. Creating it again returns the same wallet.

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/create \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "network": "stellar", "walletPin": "123456" }'

const res = await fetch('https://api.hodle.com.br/api/wallet/create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ network: 'stellar', walletPin: '123456' }),
})
const { data } = await res.json()
// data.address → "G…"

Response 201

{
  "success": true,
  "data": {
    "id": "6ad96f9124b1c5b037ec6fed",
    "address": "GCHZCGL3DQ4BBVK2UCDRTIBSAJPGBQJZMDVZHPXVNRA6X5IWT7Y33ZJD",
    "network": "stellar",
    "balance": 0
  }
}

2. Receive USDC

Send USDC on Stellar (the official USDC asset, issuer GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN) to the wallet's G… address. No memo is needed. Other Stellar assets are not credited.

3. Buy USDC with Pix

Use Deposit Asset with asset: "USDC" and network: "stellar". The account (or sub-account) must already have its Stellar wallet; the USDC is delivered to it.

{ "asset": "USDC", "network": "stellar", "value": 10000 }

4. Read the balance

Wallet Get includes the Stellar wallet:

{
  "addresses": { "stellar": "GCHZ…ZJD" },
  "balances": [
    { "network": "stellar", "asset": "USDC", "amount": "25.00" },
    { "network": "stellar", "asset": "XLM", "amount": "0.00" }
  ]
}

Balances are cached for 30 seconds; pass sync: true for a fresh read. POST /api/wallet/list lists the wallet with type: "STELLAR_CLIENT_GENERATED" and its address.

5. Pay a Pix

POST /api/wallet/payout/stellar pays a Pix key or a Pix QR code in BRL from the wallet's USDC. It runs every check Wallet Payout runs (limits, third-party rules, rate limit, duplicates) and answers 202 while the payout settles.

Payouts from Stellar are being rolled out. While they are not enabled for your account the endpoint answers 403.

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/payout/stellar \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "value": 1000, "pixKey": "[email protected]", "walletPin": "123456", "externalId": "order-123" }'

Response 202

{
  "success": true,
  "data": {
    "id": "6ad9…",
    "trackId": "1dbf…",
    "stage": "SENT",
    "amountInRaw": "19230000",
    "txHash": "aa…"
  }
}

amountInRaw is the USDC debited, with 7 decimals (19230000 = 1.923 USDC). Follow the payout with GET /api/wallet/payout/:transactionId and the PAYOUT_SUCCESSFUL / PAYOUT_FAILED webhooks.