Documentation Index
Fetch the complete documentation index at: https://docs.nexfi.robert.dpdns.org/llms.txt
Use this file to discover all available pages before exploring further.
Bridge Routes and Orders
This page mirrors the detailed design style for Bridge user-side APIs, including endpoint purpose, request fields, response fields, examples, and business notes.
GET /api/v1/bridge/routes
Purpose
Queries available bridge routes before the user confirms a cross-chain transfer.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|
fromChainId | Integer | Yes | Source chain ID. | 1 |
toChainId | Integer | Yes | Destination chain ID. | 8453 |
fromToken | String | Yes | Source asset symbol or identifier. | USDC |
toToken | String | Yes | Destination asset symbol or identifier. | USDC |
amount | String | Yes | Bridge amount. | 1000 |
walletAddress | String | No | Wallet address used by some providers for quote context. | 0xabc... |
Example Request
GET /api/v1/bridge/routes?fromChainId=1&toChainId=8453&fromToken=USDC&toToken=USDC&amount=1000&walletAddress=0xabc...
Response Fields
| Field | Type | Description | Example |
|---|
data.routes | Array | Available route list. | [] |
data.routes[].routeId | String | Platform route ID. | route_base_usdc_01 |
data.routes[].providerKey | String | Provider identifier. | across |
data.routes[].bridgeName | String | Bridge display name. | Across |
data.routes[].estimatedReceiveAmount | String | Estimated destination amount after fees. | 998.42 |
data.routes[].bridgeFeeAmount | String | Bridge fee amount. | 1.10 |
data.routes[].networkFeeAmount | String | Network fee amount. | 0.48 |
data.routes[].estimatedArrivalSeconds | Integer | Estimated arrival time in seconds. | 420 |
data.routes[].riskLevel | String | Route risk level: low, medium, or high. | medium |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"routes": [
{
"routeId": "route_base_usdc_01",
"providerKey": "across",
"bridgeName": "Across",
"estimatedReceiveAmount": "998.42",
"bridgeFeeAmount": "1.10",
"networkFeeAmount": "0.48",
"estimatedArrivalSeconds": 420,
"riskLevel": "medium"
}
]
}
}
Notes
- Routes should be sorted by platform strategy rather than returned arbitrarily.
- If no route is available, backend should return an empty array instead of a synthetic fallback.
- Frontend should display bridge fee and network fee separately.
POST /api/v1/bridge/orders
Purpose
Creates a platform bridge order so the system can track the bridge lifecycle.
Request Body
| Parameter | Type | Required | Description | Example |
|---|
routeId | String | Yes | Selected route ID. | route_base_usdc_01 |
fromChainId | Integer | Yes | Source chain ID. | 1 |
toChainId | Integer | Yes | Destination chain ID. | 8453 |
fromToken | String | Yes | Source asset. | USDC |
toToken | String | Yes | Destination asset. | USDC |
amount | String | Yes | Bridge amount. | 1000 |
senderAddress | String | Yes | Source wallet address. | 0xabc... |
recipientAddress | String | Yes | Destination wallet address. | 0xabc... |
Example Request
{
"routeId": "route_base_usdc_01",
"fromChainId": 1,
"toChainId": 8453,
"fromToken": "USDC",
"toToken": "USDC",
"amount": "1000",
"senderAddress": "0xabc...",
"recipientAddress": "0xabc..."
}
Response Fields
| Field | Type | Description | Example |
|---|
data.orderId | String | Platform order ID. | bridge_20260511_0001 |
data.status | String | Initial normalized order status. | created |
data.providerKey | String | Bound provider. | across |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "bridge_20260511_0001",
"status": "created",
"providerKey": "across"
}
}
Notes
- Creating an order means the backend starts tracking it; it does not mean bridging is already complete.
- The user still signs and broadcasts the source-chain transaction locally.
- The platform order should later be linked to provider order IDs and source-chain transaction hashes.
GET /api/v1/bridge/orders/{id}
Purpose
Returns normalized bridge order status by platform order ID.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|
id | String | Yes | Platform order ID. | bridge_20260511_0001 |
Response Fields
| Field | Type | Description | Example |
|---|
data.orderId | String | Platform order ID. | bridge_20260511_0001 |
data.providerKey | String | Provider identifier. | across |
data.status | String | Normalized order status. | bridging |
data.sourceTxHash | String | Null | Source-chain transaction hash. | 0x123... |
data.updatedAt | String | Last update time. | 2026-05-11T10:00:00.000Z |
data.failReason | String | Null | Failure reason if any. | null |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "bridge_20260511_0001",
"providerKey": "across",
"status": "bridging",
"sourceTxHash": "0x123...",
"updatedAt": "2026-05-11T10:00:00.000Z",
"failReason": null
}
}
Order Status Semantics
| Status | Meaning |
|---|
created | Order is created and waiting for the user to submit the source transaction. |
pending_source | Source-side activity is detected but bridge execution is not fully underway yet. |
bridging | Provider is actively executing the bridge. |
completed | Destination-side settlement is complete. |
failed | Bridge execution failed. |
cancelled | Order was cancelled or expired. |
Notes
- Frontend should use the normalized platform status instead of raw provider states.
sourceTxHash may be empty before the user broadcasts the source-chain transaction.- Failure views should display both
failReason and suggested next steps when available.