Skip to main content
Use GET /swap/{id} to show the latest status for a swap created with your API key. If you set externalId on quote creation, keep it with the swap record and use it as your first support reference. Add the LightSwap swap ID when one already exists.

​
Statuses

StatusMeaning
waiting_depositWaiting for the user to send funds.
deposit_detectedA deposit was detected and is waiting for confirmations.
underpaidThe detected deposit amount was incomplete.
processingThe swap is being processed.
completedThe swap finished.
refundedFunds were refunded.
failedThe swap failed.
expiredThe deposit was not detected before the deadline.
Terminal statuses:
  • completed
  • refunded
  • failed
  • expired
Poll every 30 seconds while the status is not terminal.

​
Error format

All errors use the same response shape. 
{
  "error": {
    "code": "quote_expired",
    "message": "Partner quote has expired.",
    "details": {}
  },
  "requestId": "request-id"
}

​
Error codes

CodeMeaningSuggested handling
invalid_api_keyThe API key is missing or invalid.Check backend configuration.
inactive_partnerThe partner account is disabled.Contact the LightSwap partner team by email.
validation_errorThe request body, headers, or parameters are invalid.Fix the request and retry.
unsupported_assetThe requested asset is not available for that network.Refresh assets and ask the user to choose another asset.
unsupported_pairThe requested pair is not available.Ask the user to choose another pair or amount.
quote_not_foundThe quote ID does not exist for this partner.Create a new quote.
quote_expiredThe quote expired before swap creation.Create a new quote.
quote_already_usedThe quote already created a swap.Retry POST /swap with the same quoteId or use the stored swap ID.
rate_limitedThe request limit was exceeded.Wait for Retry-After, then retry.
provider_unavailableA route service is temporarily unavailable.Retry later or ask the user to choose another pair.
swap_not_foundThe swap ID does not exist for this partner.Check the stored swap ID.
internal_errorThe request failed on the server.Retry later and contact support with your externalId and swap ID if it continues.

​
Troubleshooting

SituationWhat to do
Quote expires before the user confirmsCreate a new quote and show the updated estimate.
Address validation failsAsk the user to check the address and selected network.
Swap remains waiting_depositConfirm the user sent the exact asset to the displayed deposit address before the deadline.
Swap is underpaidDo not ask the user to send more unless LightSwap tells you to.
API returns rate_limitedBack off using Retry-After; avoid tight retry loops.
You need supportSend externalId first, then the swap ID and deposit transaction hash if available. Do not send private keys or seed phrases.