DePix swap

Use POST /api/wallet/swap to spend DePix already held in your Hodle Spark wallet. Hodle exchanges it on the DePix/BTC Flashnet pool and delivers BTC to a Spark address or pays a Lightning address. This operation does not create a PIX charge and cannot spend DePix held on Liquid.

Prerequisites

• A production API key and an account with swaps enabled (SWAP). Spark DePix swaps are unavailable in sandbox.
• An initialized Spark wallet with spendable DePix. Unlock the wallet once in the app to register its Spark identity.
• The wallet PIN and its protectedSymmetricKey, available through Wallet Keys. The PIN must unlock the wallet selected by subAccountId, when supplied.

A supplied destination changes where BTC is delivered. It does not select the wallet to debit or authorize spending from an arbitrary Spark address.

POST /api/wallet/swap

The API verifies wallet authorization, records the request, and returns 202 Accepted. The worker checks the pool output before transferring DePix. Follow the swapId to learn whether delivery completed.

const response = 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: 'DEPIX',
    toAsset: 'BTC',
    network: 'spark',
    amount: '25.00',
    clientRequestId: 'depix-order-123',
    minAmountOutSats: 400,
    maxSlippageBps: 100,
    walletPin: process.env.HODLE_WALLET_PIN,
    protectedSymmetricKey: process.env.HODLE_PROTECTED_SYMMETRIC_KEY,
  }),
})
const swap = await response.json()

Omit address to receive BTC in the selected wallet's Spark address, or pass another valid mainnet spark1… address.

{
  "success": true,
  "swapId": "f3cda087-85f9-4e17-a37a-208e58231fe1",
  "clientRequestId": "depix-order-123",
  "status": "PENDING",
  "fromAsset": "DEPIX",
  "toAsset": "BTC",
  "amountIn": "2500000000",
  "network": "spark",
  "destination": "spark1pgss92n427yh3ghz5dq0j93ph3p9lrmhy7enrus02uusmd6ktlx23t88en8f8j",
  "minAmountOutSats": 400,
  "maxSlippageBps": 100,
  "maxLightningFeeSats": 0
}

amount is a decimal string in whole DePix. amountIn is an integer string in raw token units: 1 DePix = 100,000,000 units. BTC amounts in the response and tracking legs are satoshis.

Request fields

Lightning delivery

Use the same endpoint and credentials with these fields:

{
  "fromAsset": "DEPIX",
  "toAsset": "BTC",
  "network": "lightning",
  "amount": "25.00",
  "clientRequestId": "depix-lightning-124",
  "address": "[email protected]",
  "minAmountOutSats": 400,
  "maxSlippageBps": 100,
  "maxLightningFeeSats": 10,
  "walletPin": "<wallet PIN>",
  "protectedSymmetricKey": "<encrypted key envelope>"
}

Hodle first transfers the entire BTC swap output to your Spark wallet. That wallet then pays an invoice obtained from the Lightning address for swap output minus maxLightningFeeSats. Only the actual routing fee is spent; the unused allowance stays in your Spark wallet.

For example, a 2,000-sat swap with a 10-sat allowance pays a 1,990-sat invoice. If the actual routing fee is 3 sats, 7 sats remain in your Spark wallet. A route that needs more than the allowance is not authorized. A Lightning failure does not repeat the DePix swap.

BOLT11 invoices are not accepted as the address input because the final payable amount is known only after the swap. The Lightning service must accept the resulting amount; an invalid or unavailable service can leave the BTC in your Spark wallet without completing the payment.

Track settlement

curl --request GET \
  --url 'https://api.hodle.com.br/api/wallet/swap/f3cda087-85f9-4e17-a37a-208e58231fe1' \
  --header "Authorization: Bearer $HODLE_API_KEY"

For a sub-account swap, append ?subAccountId=YOUR_SUBACCOUNT_ID. An unrelated API key, or a request for the wrong sub-account, receives 404.

Poll every few seconds until a terminal state. A successful POST only confirms acceptance; COMPLETED confirms destination delivery. This endpoint does not emit DEPOSIT_ASSET_SUCCESS; that event belongs to PIX deposits.

The response includes legs, each with status, originChain, destinationChain, originTxHash, destinationTxHash, actualAmountOut, and error:

Confirmed legs remain recorded even when a later step fails. Repeated worker delivery cannot repeat the debit. An interrupted worker can leave RUNNING until reconciliation; a Lightning payment still unconfirmed after the bounded settlement check is reported as STRANDED, never as completed.

Retrying HTTP requests

Retry the identical request with the same clientRequestId after an HTTP timeout. Once the wallet unlock check is free, you receive 200 with the original swapId and current status, and no new job is created. Changing the amount, destination, network, wallet, limits, or reference while reusing the ID returns 409 IDEMPOTENCY_CONFLICT.

A replay of a failed request reports its existing failure; it does not restart settlement. Never use a new ID to recover an uncertain or stranded transfer. Wallet authorization expires after five minutes if the worker has not consumed it.

Costs and errors

The pool fee is included in the BTC output; the current DePix/BTC pool lists a 1.40% fee. There is no PIX deposit fee on this balance swap and no additional Hodle swap markup in this route. Lightning routing fees are paid from the BTC already credited to the user's Spark wallet. See the pool for the token and pool identifiers.

Pool minimums, spendable balance, and live settlement are checked by the worker. Their failures appear in the tracking response rather than as a synchronous POST rejection.