Open app

API reference

Markdown

Read a swap order

GET/v2/swaps/{id}

Read a swap order with an owner session or destination proof.

Authentication: Required: the order’s owner session in X-Session-ID, or the destination proof ?verify=<destination-address> (read-only).

A missing order, a wrong session and a wrong verify address all return the same 404 (checked live). An order handled by support only answers 409 conflict; see locked orders.

#Parameters

Name In Type Required Description
id path string (pattern ^[A-Za-z0-9:_-]{1,128}$) Yes Public order identifier. Not a credential: every read still requires the owner session or the destination proof.

#Response

200 returns an object with:

  • orderId · string · required
  • product · "swap" · required
  • status · "awaiting_deposit" · "awaiting_xmr1" · "awaiting_trx1" · "awaiting_zec1" · "processing" · "completed" · "failed" · "expired" · "refunded" · "needs_review" · required
  • asset · "xmr" · "trx" · "zec" — Registered native-bridge asset key, never a display symbol.
  • direction · "deposit" · "withdraw" — deposit mints the wrapped asset from a native-coin deposit; withdraw returns the native coin against the wrapped asset.
  • chainId · integer or null · required — Non-negative integer chain identifier.
  • toAddress · string · required
  • depositAddress · string · required
  • createdAt · string or null · required
  • updatedAt · string or null · required
  • fromChainId · integer · required — Non-negative integer chain identifier.
  • depositChainId · integer · required — Non-negative integer chain identifier.
  • fromToken · string · required
  • depositToken · string · required
  • fromTokenSymbol · string · required
  • depositTokenSymbol · string · required
  • fromTokenDecimals · integer (0–36) · required
  • depositTokenDecimals · integer (0–36) · required
  • fromAmount · string (atomic integer) · required — Positive base-10 integer in the asset’s atomic unit.
  • depositAmount · string (atomic integer) · required — Positive base-10 integer in the asset’s atomic unit.
  • toChainId · integer · required — Non-negative integer chain identifier.
  • toToken · string · required
  • toTokenSymbol · string · required
  • toTokenDecimals · integer (0–36) · required
  • expectedOutput · string
  • depositTxHash · string or null
  • receivingTxHash · string or null
  • sessionId · string or null
  • refundAddress · string or null
  • refundRequestedAt · string or null
  • expiresAt · string
  • amountUsd · number
  • bonusStage · "none" · "coinflip"
  • coinflipRequested · boolean
  • fundingProvider · "privy" or null
  • integratorFeeUsd · number or null
  • customerState · one of the variants below · required — Authoritative customer display/action state. Clients must not infer lifecycle from status or resource presence.
    • kind = "awaiting_deposit"
    • kind = "processing"
    • kind = "action_required"
    • kind = "paused"
    • kind = "completed"
    • kind = "refunded"
    • kind = "expired"
    • kind = "failed"
  • confirmations · number
  • requiredConfirmations · number
  • depositObserved · boolean
  • errorMessage · string or null · required
  • actualOutput · string — What the customer received, in atomic units of deliveredToken when present, otherwise of toToken. Only on completed orders.
  • deliveredToken · object — Present only when the order completed in a different asset than toToken; actualOutput is then denominated in this token.
    • chainId · integer · required — Non-negative integer chain identifier.
    • token · string · required
    • symbol · string · required
    • decimals · integer (0–36) · required
  • coinflipLost · boolean · required
  • hasReview · boolean · required
  • refundRecovery · object or null
    • kind · "wrong_chain" · "source" · "table_deposit" · required
    • phase · "address_required" · "requested" · "in_progress" · required
    • chainId · integer · required — Non-negative integer chain identifier.
    • asset · object · required
      • Nested fields: see openapi.json.
    • amountAtomic · string · required
    • requestedAt · string or null · required
    • suggestedAddress · string — An address the order already has on file for this chain (for table_deposit, the table's payout address), offered as the prefill while phase is address_required. An offer only: nothing is sent to it until it is submitted.
    • destination · object — Where the refund goes once that is decided (phase requested or in_progress). source is customer when someone submitted the address, sender when the refund returns to the wallet the deposit came from without anyone having to submit one.
      • Nested fields: see openapi.json.
  • rewards · object
    • status · "pending" · "earned" · "not_eligible" · required
    • wagyuEarned · number · required
    • wagyuBonusEarned · number · required
    • wagyuCompensation · number
    • wagyuTotalEarned · number · required
    • policyKey · string or null · required
  • depositAddressForms · array of object
    • kind · "shielded" · "transparent" · required
    • address · string · required
  • sourceDepositAddress · string or null
  • observedDepositTxHash · string
  • observedDepositAmount · string (atomic integer) — Positive base-10 integer in the asset’s atomic unit.
  • fundedExpectedOutput · string (atomic integer) — Positive base-10 integer in the asset’s atomic unit.
  • refund · object
    • txHash · string · required
    • chainId · integer · required — Non-negative integer chain identifier.
    • toAddress · string · required
  • coinflip · object or null
    • eligible · boolean · required
    • accepted · boolean or null · required
    • seedHash · string · required
    • clientSeed · string · required
    • assetSymbol · string
    • assetKey · "xmr" · "trx" · "zec" or "xmr" · "btc" · "sol" · "eth" · "zec" — Asset a coinflip was staked in: a table pool asset or a bridge asset.
    • result · number
    • won · boolean
    • serverSeed · string
    • resolvedAt · string
    • side · "cow" · "milk" or null
    • currentRound · number
    • currentMultiplier · number
    • finalMultiplier · number or null
    • finalWon · boolean or null
    • rounds · array of object
      • Nested fields: see openapi.json.
    • policy · object
      • Nested fields: see openapi.json.
    • decisionDeadline · string
    • mode · "session"
    • balanceAtomic · string (pattern ^0*[0-9]+$) — Non-negative base-10 integer in the asset’s atomic unit.
    • creditedInAtomic · string (pattern ^0*[0-9]+$) — Non-negative base-10 integer in the asset’s atomic unit.
    • wageredAtomic · string (pattern ^0*[0-9]+$) — Non-negative base-10 integer in the asset’s atomic unit.
    • minBetAtomic · string (pattern ^0*[0-9]+$) — Non-negative base-10 integer in the asset’s atomic unit.
    • maxBetAtomic · string (pattern ^0*[0-9]+$) — Non-negative base-10 integer in the asset’s atomic unit.
    • wagyuPoints · number
    • refusal · "not_a_positive_amount" · "above_balance" · "below_minimum" · "below_payout_minimum" · "above_exposure_cap" · "limits_unavailable"
    • pendingTopUp · object
      • Nested fields: see openapi.json.
  • twap · object or null
    • enabled · true · required
    • status · "running" · "completed" · "failed" · required
    • side · "buy" · "sell"
    • filledPercent · number · required
    • chunksCompleted · number · required
    • chunksTotal · number · required
    • estimatedTimeRemainingMs · number
    • estimatedTimeRemaining · string
    • startedAt · string · required
    • expectedCompleteAt · string
    • completedAt · string
  • route · object or null
    • provider · string · required
    • tool · string · required
    • txHash · string or null · required
    • toChainId · integer · required — Non-negative integer chain identifier.
    • status · "pending" · "done" · "refunded" · "failed" · "partial" · "unavailable" · required
    • statusMessage · string or null · required
  • routing · object
    • topology · "single" · "parallel" · required
    • branchCount · integer · required
    • phase · "preparing" · "executing" · "recovering" · "settled" · "attention" · "unavailable" · required
    • status · "pending" · "done" · "partial" · "failed" · "unavailable" · required
    • branches · object · required
      • Nested fields: see openapi.json.
    • routes · array of object · required
      • Nested fields: see openapi.json.
  • hlFills · array of object or null
    • tradeId · string (pattern ^\d+$)
    • coin · string (pattern ^@\d+$)
    • txHash · string (max 66, pattern ^0x(?!0{64}$)[0-9a-fA-F]{64}$)
    • time · integer · required
    • side · "Buy" · "Sell" · required
    • price · number · required
    • size · number · required
    • value · number · required
    • fee · number · required
    • feeToken · string · required
    • twapId · integer
  • hlFillsStatus · "pending" · "complete" · "incomplete"
  • hlFillsNextCursor · string (pattern ^[1-9]\d{0,18}$) or null

Errors use the standard error envelope: branch on code, never on the message.

#Example

curl
curl 'https://api-beta.wagyu.xyz/v2/swaps/<orderId>' \
  -H 'x-session-id: <sessionId>'
JavaScript
const res = await fetch('https://api-beta.wagyu.xyz/v2/swaps/<orderId>', {
  headers: {"x-session-id":"<sessionId>"},
});
const data = await res.json();
Python
import requests

res = requests.get('https://api-beta.wagyu.xyz/v2/swaps/<orderId>', headers={"x-session-id":"<sessionId>"}, timeout=30)
data = res.json()

No response is captured for this route: it needs a real order. The response fields above come from the live contract.

Esc

Tip: every page is also plain Markdown, and /llms.txt indexes them for AI tools.