curl -H "Authorization: Bearer lid_live_..." \
"https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL"
const res = await fetch(
'https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL',
{ headers: { Authorization: 'Bearer lid_live_...' } }
)
const { options, unavailable, bestSavingUsd } = await res.json()
// options[0] is the cheapest route (ascending feePct)
{
"toCurrency": "USDC_SOL",
"options": [
{
"fromCurrency": "USDT_BASE",
"toCurrency": "USDC_SOL",
"availableFrom": "412.550000",
"fromAmount": "412.550000",
"toAmount": "409.211044",
"feePct": 0.8123,
"feeUsd": 3.35,
"receiveUsd": 409.21,
"executionMode": "external",
"estimatedSeconds": 22
}
],
"unavailable": [
{ "fromCurrency": "TRX", "reason": "Conversion amount too small for this pair" }
],
"bestSavingUsd": 18.42
}
Conversions
Get best route
Rank your Liddie balances by real all-in cost to find the cheapest crypto conversion route into a target currency, including fees and learned minimums.
GET
/
api
/
v1
/
conversions
/
best-route
curl -H "Authorization: Bearer lid_live_..." \
"https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL"
const res = await fetch(
'https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL',
{ headers: { Authorization: 'Bearer lid_live_...' } }
)
const { options, unavailable, bestSavingUsd } = await res.json()
// options[0] is the cheapest route (ascending feePct)
{
"toCurrency": "USDC_SOL",
"options": [
{
"fromCurrency": "USDT_BASE",
"toCurrency": "USDC_SOL",
"availableFrom": "412.550000",
"fromAmount": "412.550000",
"toAmount": "409.211044",
"feePct": 0.8123,
"feeUsd": 3.35,
"receiveUsd": 409.21,
"executionMode": "external",
"estimatedSeconds": 22
}
],
"unavailable": [
{ "fromCurrency": "TRX", "reason": "Conversion amount too small for this pair" }
],
"bestSavingUsd": 18.42
}
“I want to end up holding X — which of my balances gets me there cheapest?”
The all-in cost of a conversion is dominated by the chain the funds start on, not by the amount, so the same target can cost several percent from one balance and under 1 % from another. This endpoint prices every balance you hold through the normal quote path (real numbers, nothing moves) and ranks them.
Candidates are capped at 8, richest first, and balances worth under $1 are ignored. An unsupported
toCurrency is 400 VALIDATION_ERROR.
Authorization
Dual auth — a secret API key with theconversions:read scope, or a dashboard JWT with the conversions:view permission. Dashboard sessions must belong to a merchant_admin, merchant_member or super_admin role; API-key callers are gated by scope only. See the Authentication guide.
Rate limit: 3/min — each call fans out one quote per candidate balance.
Each call fans out one real quote per candidate balance (up to 8) and is limited to 3/min — call it once when the user opens the conversion flow, not on every input change.
curl -H "Authorization: Bearer lid_live_..." \
"https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL"
const res = await fetch(
'https://api.liddie.io/api/v1/conversions/best-route?toCurrency=USDC_SOL',
{ headers: { Authorization: 'Bearer lid_live_...' } }
)
const { options, unavailable, bestSavingUsd } = await res.json()
// options[0] is the cheapest route (ascending feePct)
{
"toCurrency": "USDC_SOL",
"options": [
{
"fromCurrency": "USDT_BASE",
"toCurrency": "USDC_SOL",
"availableFrom": "412.550000",
"fromAmount": "412.550000",
"toAmount": "409.211044",
"feePct": 0.8123,
"feeUsd": 3.35,
"receiveUsd": 409.21,
"executionMode": "external",
"estimatedSeconds": 22
}
],
"unavailable": [
{ "fromCurrency": "TRX", "reason": "Conversion amount too small for this pair" }
],
"bestSavingUsd": 18.42
}
Query parameters
string
required
The target currency you want to end up holding.
Response fields
string
The requested target currency.
array
Cheapest first (ascending
feePct). Empty when nothing can reach the target.Show properties
Show properties
string
The source balance priced for this route.
string
The target currency.
string
Your whole available balance.
string
The source amount priced (the same figure as
availableFrom, rounded down to on-chain precision).string
What you would receive, decimal string.
number
Effective all-in commission in percent (4 dp) —
0.84 means 0.84 %.number
USD value of the fee.
number
USD value of the output.
string
"internal" or "external" for that route.number
Present only when the route reports one; may be
null.array
number
feeUsd of the worst priced option minus the best (0 when fewer than two options priced).Errors
| Status | Body | Why |
|---|---|---|
| 403 | { "ok": false, "error": { "code": "CONVERSIONS_DISABLED", "message": "…" } } — the envelope (unlike /quote and POST /, which send a flat body) | Feature switched off platform-wide. |
| 400 | { "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "…" } } | Missing/malformed field or unsupported toCurrency. |
| 400 | { "ok": false, "error": { "code": "NO_SCOPE", "message": "…" } } | No merchant context on the credential. |
See also
- Get cheaper targets: the inverse question — same source, better destination.
- Get a quote: price the route you picked before executing.
- Execute a conversion: run the winning route.
- Conversions Overview: why the source chain dominates the all-in cost.