Quotes and swaps

Price and execute conversions.

Quotes are short-lived price commitments. Swaps consume a quote; limit orders wait for one.

Create a quote#

bash

curl -s -X POST "$JUICEPAY_URL/v1/quotes" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{
    "from": { "asset": "USDC", "amount": "40000.00" },
    "to": { "asset": "NGNX" },
    "ttl": 30
  }'

json

{
  "id": "qt_3rP8vB",
  "object": "quote",
  "from": { "asset": "USDC", "amount": "40000.00" },
  "to": { "asset": "NGNX", "amount": "61928400.00" },
  "rate": "1548.21",
  "price_impact": "0.0012",
  "network_fee": "0.41",
  "platform_fee": "0.00",
  "venues": [
    { "name": "venue_alpha", "weight": "0.62" },
    { "name": "venue_beta", "weight": "0.28" },
    { "name": "venue_gamma", "weight": "0.10" }
  ],
  "created": "2026-08-19T09:14:02Z",
  "expires_at": "2026-08-19T09:14:32Z"
}

Field	Notes
`rate`	Effective rate after all fees and impact.
`price_impact`	Fractional move caused by your own size.
`venues`	Contributing venues and their weights.
`platform_fee`	Itemised separately; zero on stablecoin pairs.

Execute a swap#

bash

curl -s -X POST "$JUICEPAY_URL/v1/swaps" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -H "Idempotency-Key: swap:qt_3rP8vB" \
  -d '{
    "quote": "qt_3rP8vB",
    "destination_chain": "solana"
  }'

An expired quote returns quote_expired. Always handle that by requesting a fresh quote and showing the new price, rather than retrying blindly.

Retrieve a swap#

bash

curl -s "$JUICEPAY_URL/v1/swaps/sw_6nR2kM" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

json

{
  "id": "sw_6nR2kM",
  "status": "settled",
  "from": { "asset": "USDC", "amount": "40000.00" },
  "to": { "asset": "NGNX", "amount": "61928400.00" },
  "destination_chain": "solana",
  "executed_rate": "1548.21",
  "created": "2026-08-19T09:14:02Z",
  "settled": "2026-08-19T09:14:18Z"
}

executed_rate will match the quote's rate unless the quote was refreshed. If they differ, the swap records the rate actually achieved and the ledger reflects it.

Limit orders#

bash

curl -s -X POST "$JUICEPAY_URL/v1/limit_orders" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -H "Idempotency-Key: lo-ngn-aug-001" \
  -d '{
    "from": { "asset": "USDC", "amount": "40000.00" },
    "to": { "asset": "NGNX" },
    "target_rate": "1600.00",
    "expires_in": 604800,
    "partial_fills": true
  }'

target_rate is the minimum acceptable rate. The order fills at or better, never worse. Funds are reserved, not escrowed — they remain in your balance and are visible as reserved until the order fills, expires, or is cancelled.

Field	Notes
`target_rate`	Minimum acceptable rate.
`expires_in`	Seconds until the order expires.
`partial_fills`	Allow fills in tranches rather than all-or-nothing.
`max_slippage`	Optional ceiling on per-fill deviation.

Cancel a limit order#

bash

curl -s -X DELETE "$JUICEPAY_URL/v1/limit_orders/lo_9jH4pL" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Cancelling releases the reservation immediately. Fills that already happened are unaffected.

Events#

Event	Fires when
`swap.executing`	Swap accepted and broadcast.
`swap.settled`	Destination asset credited.
`swap.failed`	Swap could not be completed.
`limit_order.working`	Order accepted and watching venues.
`limit_order.partially_filled`	A tranche filled.
`limit_order.filled`	Fully filled.
`limit_order.canceled`	Cancelled or expired.