LCX Liberty. American DeFi. Your keys. Your assets. Your control.
Stablecoin swap
POST /v1/stablecoins/swap returns the quote and a transaction whose minimum output is set from your tolerance.
Request
/v1/stablecoins/swapEverything /v1/stablecoins/quote takes, plus a taker. It quotes under the same rules and builds the transaction in the same call, its minimum output set to stablecoin.minOut.
| Field | Type | Description |
|---|---|---|
| chainId* | number | The chain both coins are on. A conversion never crosses chains: there is no toChainId here. |
| tokenIn* | string | The stablecoin being sold. Must be in the registry for chainId, or the request is refused with not_a_stablecoin. |
| tokenOut* | string | The stablecoin being bought. The same rule, and it must differ from tokenIn. |
| amountIn* | string | The amount to sell in base units, as on /v1/quote. Required unless amount is sent; never both. |
| amount | string | The same amount in human units, e.g. "250000", scaled by the token's own decimals. |
| decimals | number | Optional and best left out, with the same rules as /v1/quote (decimals_mismatch, decimals_required). |
| maxParDeviationBps | number | Your tolerance: how far below the anchor you accept, in basis points. Default 50, above 0 and at most 100, and it may be fractional (2.5). A quote further below the anchor is refused with below_tolerance; a value out of range with bad_tolerance. |
| slippageBps | number | The bound against the quote itself. Default 30. The swap's minimum output is the tighter of this and your tolerance; see Tolerance and the floor. |
| allowOffPeg | boolean | Default false. Buying a coin that trades more than 1% from its peg is refused with off_peg unless this is true. |
| integrator | string | Your integration, exactly as on /v1/quote: an address, or a slug we registered for you. A fee you registered is taken from the output and stated in quote.fee; none is taken otherwise. |
| taker* | string | The address that sends the transaction and receives the output. Missing, the request is refused with bad_request. |
| deadlineSecs | number | Seconds until the on-chain deadline, as on /v1/build: default 300, at most 3600, above zero. |
chainId*numberThe chain both coins are on. A conversion never crosses chains: there is no toChainId here.
tokenIn*stringThe stablecoin being sold. Must be in the registry for chainId, or the request is refused with not_a_stablecoin.
tokenOut*stringThe stablecoin being bought. The same rule, and it must differ from tokenIn.
amountIn*stringThe amount to sell in base units, as on /v1/quote. Required unless amount is sent; never both.
amountstringThe same amount in human units, e.g. "250000", scaled by the token's own decimals.
decimalsnumberOptional and best left out, with the same rules as /v1/quote (decimals_mismatch, decimals_required).
maxParDeviationBpsnumberYour tolerance: how far below the anchor you accept, in basis points. Default 50, above 0 and at most 100, and it may be fractional (2.5). A quote further below the anchor is refused with below_tolerance; a value out of range with bad_tolerance.
slippageBpsnumberThe bound against the quote itself. Default 30. The swap's minimum output is the tighter of this and your tolerance; see Tolerance and the floor.
allowOffPegbooleanDefault false. Buying a coin that trades more than 1% from its peg is refused with off_peg unless this is true.
integratorstringYour integration, exactly as on /v1/quote: an address, or a slug we registered for you. A fee you registered is taken from the output and stated in quote.fee; none is taken otherwise.
taker*stringThe address that sends the transaction and receives the output. Missing, the request is refused with bad_request.
deadlineSecsnumberSeconds until the on-chain deadline, as on /v1/build: default 300, at most 3600, above zero.
* required
| Field | Type | Description |
|---|---|---|
| Idempotency-Key | string | Optional. 1 to 128 visible ASCII characters; anything else is refused with bad_request. See Retries and idempotency. |
Idempotency-KeystringOptional. 1 to 128 visible ASCII characters; anything else is refused with bad_request. See Retries and idempotency.
Example
curl -X POST https://swap-api.lcx.com/v1/stablecoins/swap \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: payout-2026-11-17-0042" \
-d '{
"chainId": 1,
"tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"tokenOut": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"amount": "250000",
"maxParDeviationBps": 10,
"taker": "0xYourWallet…"
}'Response
The quote response, data.quote and data.stablecoin as on /v1/stablecoins/quote, plus data.transaction:
"transaction": {
"to": "0x…",
"data": "0x…",
"value": "0",
"gas": "412000",
"chainId": 1
}to, data and value are the shape every wallet library accepts. The calldata's minimum output is stablecoin.minOut: if the market moves past it before the transaction lands, the swap reverts on chain rather than paying less. A refusal from the build step, such as price_moved or store_unavailable, comes back as it does from /v1/build.
/v1/allowance before sending. A swap from a coin with no allowance reverts, and the revert costs gas.Retries and idempotency
A payout or a sweep is often retried by a job runner, and a retry should not produce a second transaction to sign. Send an Idempotency-Key with the request:
- The same key with the same body, within 24 hours, returns the first answer, unchanged.
- The same key with a different body is refused with
idempotency_key_reused. - Keys are scoped to your account: every API key of the account shares one set, and another account's keys never collide with yours.
- Only a successful answer is remembered. A refusal is not, so the same key can be sent again once the cause is fixed.
A replayed answer is the first transaction as it was, deadline included. If that deadline has passed, sending it reverts. Read a replay as "this request was already answered", and keep your own record of what was signed: the key stops a duplicate answer, and only your signer can stop a duplicate signature.