The API behind every swap.

• You bring the backend. The reference client in assets/js/api.js talks to it. With no backend configured, the site runs a built-in mock or a local wallet preview, so pages work while you build.
• The agents map to the flow. Oracle quotes, Router routes, Sentinel watches the chain, Executor swaps and Courier delivers. Your backend fills the Order object; the agent tags are just labels on the events it returns.
• No account model. There is no login, no user object and no session. An order is a standalone record with its own ID, and the browser is the only place a visitor keeps a list of them.

• api.baseUrl is your API root, for example https://api.ghostex.ai/v1. Trailing slashes are removed, then each path is appended. Leave it empty to run the local mock or wallet preview.
• api.timeoutMs aborts a request that takes too long (default 15000). api.pollMs is how often the order page refreshes an open order (default 5000).
• api.headers is an optional map of extra request headers. It is public, because it ships in the page source, so never put a secret in it.

• JSON in, JSON out. Requests send Accept: application/json, plus Content-Type: application/json on a POST, plus anything in api.headers.
• No cookies. Requests are sent with credentials: 'omit' and cache: 'no-store', and are aborted after api.timeoutMs.
• Authentication. The reference client sends no credentials of its own. If your integration needs keys, they travel in the public api.headers, so treat them as non-secret. Arrange anything stronger with us at support@ghostex.ai.
• Amounts and times. Amounts are JSON numbers in whole units of the asset, so 0.1 BTC is 0.1. Times are milliseconds since the Unix epoch.
• Currency codes. Use the code values from assets/js/currencies.js, currently 43 assets across 31 networks. Keep the two lists in sync. The Supported assets page shows every code.

{ "error": { "code": "ADDRESS", "message": "This is not a valid Ethereum address.", "field": "address" } }

message is shown to the visitor, so write it for people. field is optional and highlights an input: from, to, amount, address, extraId, refundAddress or refundExtraId. A plain { "code", "message" } or { "error": "message" } body works too.

{
  "id": "GX7K2QF9MA",
  "createdAt": 1727250000000,
  "expiresAt": 1727251800000,
  "type": "fixed",
  "direction": "from",
  "status": "awaiting_deposit",
  "statusAt": 1727250000000,
  "from": { "code": "BTC", "amount": 0.1, "depositAddress": "bc1q...",
            "depositExtraId": null, "depositExtraIdName": null },
  "to":   { "code": "XMR", "amount": 42.1234, "address": "4AdUndXHHZ...",
            "extraId": null, "estimated": false },
  "refund": { "address": "bc1q...", "extraId": null },
  "rate": 421.23,
  "effectiveRate": 421.234,
  "fee": { "percent": 0.48, "amountFrom": 0.00048, "usd": 31.2 },
  "usd": { "from": 6500.1, "to": 6468.9 },
  "confirmations": { "current": 0, "required": 2 },
  "txIn": null,
  "txOut": null,
  "depositAt": null,
  "completedAt": null,
  "events": [
    { "t": 1727250000000, "agent": "SYSTEM", "text": "Order GX7K2QF9MA created", "level": "info" }
  ],
  "demo": false
}

• status moves awaiting_deposit, confirming, exchanging, sending, completed. Terminal alternatives are expired (no deposit before expiresAt) and refunded.
• from.depositAddress is where the user sends funds. depositExtraId and depositExtraIdName carry a required memo or destination tag, or null.
• txIn and txOut are null or { "hash": "..." }. txIn.from is the sending address of the deposit once detected. It is where a refund goes when the order has no refund address. Leave it out for hidden-sender assets.
• events is the log, oldest first: t in ms, agent (ORACLE, ROUTER, SENTINEL, EXECUTOR, COURIER or SYSTEM), plain-text text, and an optional level.
• demo must be false in production. When true, the order page shows a demo notice.

A refunded order also says where the money went. Return these in the same response that first reports refunded, because the order page stops polling at a terminal status.

"txIn":   { "hash": "9f2c...", "from": "bc1q..." },
"refund": { "address": "bc1q...", "extraId": null, "source": "sender", "tx": { "hash": "4e1a..." } }

• refund.address is the address actually refunded, set even when the order had no refund address. refund.source is refund_address or sender. refund.tx is the refund transaction.

• Charge the same flat 0.48% fee the site quotes, included in the amount, with the payout network fee already covered.
• Use the same currency codes as currencies.js, and issue IDs with the configured prefix (GX plus 8 characters).
• Send every refund automatically, never on a support request: to the refund address, or back to the sending address when none was given.
• Hold a fixed rate for 30 minutes, reprice a floating order at execution, and enforce the Lightning payout rules the site already checks.
• Add the API origin to CORS and to connect-src, return demo: false on every order, and keep secrets out of the public config.