Swap API Reference

Complete endpoint reference for the Token Swap API.

Base URL

https://api.rach.finance

Authentication

Endpoint group	Auth method
`/api/v1/swap/quote`	API Key (`X-API-Key` header)
`/api/v1/swap/:customerID`	API Key (`X-API-Key` header)
`/api/v1/swap/:customerID/history`	API Key (`X-API-Key` header)
`/api/v1/swap/analytics/*`	JWT Token (`Authorization: Bearer`)

GET /api/v1/swap/quote

Returns a price quote for a swap. Does not execute anything. Quotes expire in 30 seconds.

Query Parameters

Parameter	Type	Required	Description
`from_chain`	string	Yes	Source chain identifier. Same-chain: `POL`, `BSC`. Cross-chain: any LiFi-supported chain (e.g. `ETH`, `ARB`, `OP`, `AVAX`). Aliases: `POLYGON`/`MATIC` → `POL`, `BNB`/`BINANCE` → `BSC`.
`to_chain`	string	Yes	Destination chain. Must equal `from_chain` for DEX swaps.
`from_token`	string	Yes	Token contract address (checksum). Use `"native"` or `""` for the chain's native coin (MATIC / BNB).
`to_token`	string	Yes	Token contract address or `"native"`.
`amount_in`	string	Yes	Input amount in base units (no decimals). Must be a positive integer.

Response

json

{
  "from_chain":         "POL",
  "to_chain":           "POL",
  "from_token":         "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "to_token":           "native",
  "from_amount":        "100000000",
  "to_amount_expected": "134521000000000000000",
  "to_amount_min":      "133948495000000000000",
  "platform_fee":       "300000",
  "estimated_seconds":  30,
  "expires_at":         1751673028
}

Field	Type	Description
`from_amount`	string	Input amount in base units
`to_amount_expected`	string	Expected output at current price (base units)
`to_amount_min`	string	Minimum output after 0.5% slippage (base units) — use this as `amount_out_min`
`platform_fee`	string	Platform fee deducted from `amount_in` (base units)
`estimated_seconds`	number	Expected settlement time
`expires_at`	integer	Unix timestamp when this quote expires (30 seconds from issue)

Error Responses

Status	Body	Cause
400	`{"error": "from_chain, to_chain, from_token, to_token and amount_in are required"}`	Missing parameters
400	`{"error": "amount_in must be a positive integer in base units"}`	Invalid amount
400	`{"error": "tokenIn and tokenOut resolve to the same address"}`	Same token for in/out

POST /api/v1/swap/:customerID

Executes a swap from the specified customer's WaaS wallet. The transaction is broadcast and a tx_hash is returned immediately. On-chain confirmation happens asynchronously.

Path Parameters

Parameter	Description
`customerID`	The customer ID used when the wallet was provisioned via WaaS

Request Body

json

{
  "from_chain":     "POL",
  "to_chain":       "POL",
  "from_token":     "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "to_token":       "native",
  "amount_in":      "100000000",
  "amount_out_min": "133948495000000000000"
}

Field	Type	Required	Description
`from_chain`	string	Yes	Source chain
`to_chain`	string	Yes	Destination chain
`from_token`	string	Yes	Token address or `"native"`
`to_token`	string	Yes	Token address or `"native"`
`amount_in`	string	Yes	Amount in base units
`amount_out_min`	string	No	Slippage floor in base units. Strongly recommended — use quote's `to_amount_min`. Defaults to `1` if omitted.

Response

json

{
  "tx_hash": "0x4a3f2e1b8c9d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3",
  "status": "pending"
}

Field	Description
`tx_hash`	On-chain transaction hash to track settlement
`status`	Always `"pending"` on successful submission

Error Responses

Status	Body	Cause
400	`{"error": "…"}`	Invalid request body
401	`{"error": "business not found in context"}`	Invalid or missing API key
500	`{"error": "customer wallet not found for …"}`	Customer has no provisioned wallet
500	`{"error": "approve failed: …"}`	ERC-20 approval failed on-chain
500	`{"error": "swap transaction failed: …"}`	Swap reverted (insufficient balance, slippage exceeded, etc.)

GET /api/v1/swap/:customerID/history

Returns paginated swap history for a specific customer wallet.

Path Parameters

Parameter	Description
`customerID`	Customer ID

Query Parameters

Parameter	Default	Description
`page`	`1`	Page number (1-based)
`limit`	`20`	Results per page (max 100)

Response

json

{
  "swaps": [
    {
      "id": 42,
      "business_id": 7,
      "customer_wallet_id": 15,
      "customer_id": "cust_abc123",
      "type": "dex",
      "from_chain": "POL",
      "to_chain": "POL",
      "dex": "quickswap",
      "router_address": "0xa5E0829CaCEd8fFDD4De3c43696c57F7D7A678ff",
      "token_in": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "token_out": "native",
      "amount_in": "100000000",
      "amount_out": "134521000000000000000",
      "platform_fee": "300000",
      "approve_tx_hash": "0xabc123...",
      "swap_tx_hash": "0x4a3f2e...",
      "status": "confirmed",
      "confirmed_at": "2026-07-04T23:55:12Z",
      "created_at": "2026-07-04T23:54:40Z",
      "updated_at": "2026-07-04T23:55:14Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}

SwapRecord Fields

Field	Description
`type`	`"dex"` (same-chain FiatSwapV2) or `"bridge"` (cross-chain LiFi)
`from_chain`	Source chain
`to_chain`	Destination chain (same as `from_chain` for DEX swaps)
`dex`	Router used: `quickswap`, `pancakeswap`, `sushiswap`, or bridge name
`router_address`	On-chain router or bridge contract address
`amount_in`	Input amount in base units
`amount_out`	Output amount in base units (set after on-chain confirmation)
`platform_fee`	Fee deducted from `amount_in` in base units
`approve_tx_hash`	ERC-20 approval tx hash (present for token→token and token→native swaps)
`swap_tx_hash`	Main swap transaction hash
`status`	`pending` / `confirmed` / `failed`
`confirmed_at`	ISO 8601 timestamp of on-chain confirmation (null while pending)

GET /api/v1/swap/analytics/overview

Returns a summary of all swaps across all customers for the authenticated merchant. Requires JWT authentication.

Query Parameters

Parameter	Default	Description
`days`	`30`	Lookback window (1–365)

Response

json

{
  "period": "Last 30 days",
  "total_swaps": 142,
  "dex_swaps": 98,
  "bridge_swaps": 44,
  "pending_swaps": 3,
  "confirmed_swaps": 136,
  "failed_swaps": 3,
  "unique_customers": 27,
  "top_from_chains": [
    { "chain": "POL", "count": 98 },
    { "chain": "BSC", "count": 44 }
  ]
}

GET /api/v1/swap/analytics/transactions

Returns a paginated, filterable list of all swaps across all customers. Requires JWT authentication.

Query Parameters

Parameter	Default	Description
`page`	`1`	Page number
`limit`	`20`	Per page (max 100)
`status`	—	Filter by status: `pending`, `confirmed`, `failed`
`type`	—	Filter by type: `dex`, `bridge`

Response

json

{
  "swaps": [ /* SwapRecord objects */ ],
  "total": 142,
  "page": 1,
  "limit": 20
}

GET /api/v1/swap/analytics/volume

Returns daily swap counts suitable for a bar chart. Requires JWT authentication.

Query Parameters

Parameter	Default	Description
`days`	`30`	Lookback window (1–365)

Response

json

{
  "period_days": 30,
  "chart": [
    { "date": "2026-06-05", "total_swaps": 8, "dex_swaps": 6, "bridge_swaps": 2 },
    { "date": "2026-06-06", "total_swaps": 12, "dex_swaps": 9, "bridge_swaps": 3 },
    { "date": "2026-06-07", "total_swaps": 5, "dex_swaps": 4, "bridge_swaps": 1 }
  ]
}

Swap API Reference ​

Base URL ​

Authentication ​

GET /api/v1/swap/quote ​

Query Parameters ​

Response ​

Error Responses ​

POST /api/v1/swap/:customerID ​

Path Parameters ​

Request Body ​

Response ​

Error Responses ​

GET /api/v1/swap/:customerID/history ​

Path Parameters ​

Query Parameters ​

Response ​

SwapRecord Fields ​

GET /api/v1/swap/analytics/overview ​

Query Parameters ​

Response ​

GET /api/v1/swap/analytics/transactions ​

Query Parameters ​

Response ​

GET /api/v1/swap/analytics/volume ​

Query Parameters ​

Response ​

Swap API Reference

Base URL

Authentication

GET /api/v1/swap/quote

Query Parameters

Response

Error Responses

POST /api/v1/swap/:customerID

Path Parameters

Request Body

Response

Error Responses

GET /api/v1/swap/:customerID/history

Path Parameters

Query Parameters

Response

SwapRecord Fields

GET /api/v1/swap/analytics/overview

Query Parameters

Response

GET /api/v1/swap/analytics/transactions

Query Parameters

Response

GET /api/v1/swap/analytics/volume

Query Parameters

Response