Advance dry-run swap
/swap/advanceTesting-only endpoint. Advance a dry-run swap to its next lifecycle state. It only works on swaps created with "dryrun": true — calling it on a real swap returns an error, real swaps move on their own.
Each call moves the swap forward by one step and fills in realistic simulated data (fake transaction hashes, confirmation counts, timestamps).
Lifecycle progression:
NEW → PENDING → CONFIRMING → EXCHANGING → SENDING → DONE
Simulated data per transition:
NEW → PENDING: deposit detected — fakefrom.tx.id, 0 confirmations,time.startsetPENDING → CONFIRMING: first confirmationCONFIRMING → EXCHANGING: all required confirmations reachedEXCHANGING → SENDING: payout initiatedSENDING → DONE: faketo.tx.id,time.finishandrateActualset
Calling advance on a swap that is already DONE returns a 400. Dry-run swaps never expire and never enter RATE_CHANGED or REFUNDING.
Prerequisites: the swap must have been created with "dryrun": true, which requires dryrun_enabled on your API key.
Authentication: HMAC-signed (v2) request — X-API-KEY, X-API-SIGN, X-API-TIMESTAMP, X-API-NONCE headers. See the Swap Aggregator Guide.
Authorization (dual-mode): same as /swap/status — the swap must belong to your key, or you include its token.
Request
Request Body (required)
Content-Type: application/json
{
id: string, required, e.g. "DRk7m3px9q" — Dry-run swap id (DR-prefixed). Only dry-run swaps can be advanced.
token: string — Optional per-swap token from /swap/create; authorizes the call from a different API key
}
Response 200
Swap advanced to the next state (data.dryrun is true)
{
code: integer, e.g. 0 — 0 = success, 1 = error
msg: string, e.g. "" — Error message (empty on success)
data: object — Swap order (returned by create, status, advance and emergency)
{
id: string, e.g. "k7m3px9qw2" — Swap id: 10 characters (dry-run swaps: "DR" + 8). Use it for status and emergency calls.
token: string, e.g. "uYx9j2k3Lm4nOp5qRs6tUw" — Per-swap access token (22 characters). Lets another API key, or a shared link, read the status. Treat it as a secret.
type: string, enum: float|fixed — Rate type
status: string, enum: NEW|PENDING|CONFIRMING|RATE_CHANGED|EXCHANGING|SENDING|REFUNDING|DONE|EXPIRED|REFUNDED|FAILED — Current status (see Get swap status)
time: object — UNIX timestamps in seconds
{
reg: integer — Swap creation time
start: integer|null — When the deposit was first detected
finish: integer|null — When the swap ended (DONE or REFUNDED)
update: integer — Last change
expiration: integer — End of the payment window
left: integer|null — Seconds left in the payment window; null once a deposit was seen or the swap ended
}
from: object — What the user sends
{
code: string, e.g. "TRX" — Currency code
coin: string, e.g. "TRX" — Coin ticker
network: string, e.g. "TRX" — Chain
name: string, e.g. "Tron" — Display name
amount: string, e.g. "1000" — Amount the user is expected to send (string, full precision)
amountDeposited: string, e.g. "0" — Sum of the confirmed deposits so far
address: string — Deposit address to show the user
reqConfirmations: integer, e.g. 1 — Confirmations we wait for before crediting a deposit
tx: object|null — The deposit transaction, once detected
{
id: string — Transaction hash
amount: string — Deposited amount
fee: string|null — Network fee (not known for deposits)
feeCurrency: string|null — Currency of the fee
timeReg: integer — When we first saw the transaction
timeBlock: integer|null — When it reached the required confirmations
confirmations: integer — Current confirmation count
}
}
to: object — What the user receives
{
code, coin, network, name — as in from
amount: string, e.g. "339.15" — Amount we pay out: the quote until the deposit is confirmed, the final amount afterwards
address: string — Destination address
tx: object|null — The payout transaction, once sent: id, amount, fee (the network fee we paid), feeCurrency, timeReg, confirmations (refreshed while you poll, until the coin's own threshold), txKey (Monero only: the transaction key that proves the payment to the recipient's address; null elsewhere)
}
refund: object
{
address: string|null — Refund address (from the create call, or from an emergency REFUND call)
tx: object|null — The refund transaction, once sent
}
issue: object — Why the swap is not simply executing, and what was decided
{
type: string|null, enum: LESS|MORE|BELOW_MINIMUM|NO_LIQUIDITY — LESS / MORE: a fixed-rate deposit under / over the ordered amount (RATE_CHANGED). BELOW_MINIMUM: the deposit is under the pair minimum. NO_LIQUIDITY: the payout is more than we hold. Both of the latter are refunded automatically.
reason: string|null — Human-readable explanation while the swap is RATE_CHANGED, REFUNDING or FAILED
needsRefundAddress: boolean — true when we want to refund but no refund address is known: send one with POST /swap/emergency (choice REFUND)
choice: string, enum: NONE|EXCHANGE|REFUND — What was decided: EXCHANGE (executed at the new rate), REFUND (being / been refunded)
}
rate: string, e.g. "0.34" — Rate at creation: to-coin per 1 from-coin
rateActual: string|null — Rate actually applied; set when the swap is DONE
fee: object — Our service fee: { percent: number, e.g. 0.25 — amount: string, in the to-coin }
slippage: number|null — Applied rate vs quoted rate, in percent; set when the deposit is credited (0 for a fixed-rate swap honoured as quoted)
proposed: object|null — While RATE_CHANGED: the re-quote the user accepts with EXCHANGE: { rate, amount }
dryrun: boolean — true for simulated swaps
url: string|null — Public status page of the swap on bitania.com (null for dry-run swaps)
}
}
Response 400
Validation or business error, for example: Only dry-run swaps can be advanced; real swaps move on their own, Dry-run swap DRk7m3px9q is already DONE and cannot be advanced
{
code: integer, e.g. 1 — Error code (1)
msg: string, e.g. "Missing required fields: from, to, amount" — Error message
data: null
}
Response 401
Authentication failed: unknown or disabled key, IP not whitelisted (Invalid credentials), or a bad signature, stale timestamp or reused nonce (Invalid signature)
{
code: integer, e.g. 1
msg: string, e.g. "Invalid credentials"
data: null
}
Response 429
Rate limit of this endpoint exhausted; wait retry_after seconds (also sent as the Retry-After header)
{
code: integer, e.g. 1
msg: string, e.g. "Rate limit exceeded. Please retry after 12 seconds."
data: null
retry_after: integer, e.g. 12
}