API_CONTRACTS

API Contracts (Draft)

This document defines framework-agnostic request/response shapes for the BFF. It mirrors Wagyu API fields closely so the BFF can normalize or pass-through safely.

Common Conventions

• All responses are JSON.

• Errors follow a consistent envelope:

  • error.code (string)

  • error.message (string, user-safe)

  • error.details (object, optional, not for end users)

---

GET /health

Response:

• status: ok | degraded

• version: string

• time: ISO-8601

---

GET /chains

Response:

• chains: array

  • chainId: number

  • name: string

  • nativeToken: string

  • minSwapUsd: number

---

POST /quote

Request:

• fromChainId: number (0 = Monero)

• toChainId: number (0 = Monero)

• fromToken: string (token address or XMR)

• toToken: string (token address or XMR)

• fromAmount: string (smallest units)

Response:

• fromAmount: string

• fromAmountUsd: string

• fromSymbol: string

• toAmount: string

• toAmountUsd: string

• toSymbol: string

• estimatedTime: number (seconds)

• minReceived: string

• integratorFee (optional, only when API key used):

  • percent: number

  • amount: string

  • amountUsd: string

---

POST /orders

Request:

• fromChainId: number

• toChainId: number

• fromToken: string

• toToken: string

• fromAmount: string

• toAddress: string

• sessionId: string (uuid v4, optional)

• twapConfig (optional; XMR orders only):

  • disabled: boolean

  • chunkSizeUsd: number (min 250)

  • intervalMs: number (1000-60000)

Response:

• orderId: string

• depositAddress: string

• depositChain: string

• depositChainId: number

• depositToken: string

• depositTokenSymbol: string

• depositAmount: string

• toAddress: string

• expectedOutput: string

• expiresAt: ISO-8601

• status: string

---

GET /orders/{orderId}

Query:

• verify: string (optional destination address for verification)

Response:

• orderId: string

• status: string

• depositAddress: string

• depositChainId: number

• depositTokenSymbol: string

• depositAmount: string

• depositTxHash: string | null

• toAddress: string

• expectedOutput: string

• actualOutput: string | null

• errorMessage: string | null

• refundTxHash: string | null

• createdAt: ISO-8601

• completedAt: ISO-8601 | null

• twap (optional):

  • enabled: boolean

  • status: pending | active | completed | failed

  • chunksCompleted: number

  • chunksTotal: number

  • filledQty: number

  • totalQty: number

  • chunkSizeUsd: number

  • intervalMs: number

  • estimatedTimeRemainingMs: number

Order Statuses:

• awaiting_deposit

• deposit_detected

• deposit_confirmed

• executing_swap

• completed

• refunding

• refunded

• failed

• expired

---

GET /orders

Query:

• session: string (uuid v4)

Response:

• orders: array

  • id: string

  • from_chain_id: number

  • from_token_symbol: string

  • from_amount: string

  • to_chain_id: number

  • to_token_symbol: string

  • to_amount_expected: string

  • to_address: string

  • status: string

  • created_at: ISO-8601

  • completed_at: ISO-8601 | null

---

POST /support/tickets

Request:

• orderId: string | null

• sessionId: string | null

• walletAddress: string | null

• category: string

• message: string

Response:

• ticketId: string

• createdAt: ISO-8601

---

Bridge API (BFF Pass-through)

GET /bridge/rates

Response:

• rates: array

  • exchange: string

  • rate: number

  • eta: string

• wagyuRate: object

  • rate: number

  • eta: string

POST /bridge/deposit

Request:

• toAddress: string (Hyperliquid address)

Response:

• orderId: string

• depositAddress: string

• destination: string

• expiresAt: ISO-8601

POST /bridge/withdraw

Request:

• toAddress: string (Monero address)

Response:

• orderId: string

• depositAddress: string

• destination: string

• expiresAt: ISO-8601

GET /bridge/order/{orderId}

Response:

• id: string

• type: deposit | withdraw

• status: awaiting_deposit | pending_confirmations | processing | completed | failed | expired

• amount: string

• confirmations: number

• requiredConfirmations: number

• tx_in: string | null

• tx_out: string | null

• failure_reason: string | null

• created_at: ISO-8601

• completed_at: ISO-8601 | null