Base URL (mainnet):
https://bridgeapi.onyx.org/api/v1| Method and path | Purpose |
|---|---|
GET /health | Operational state and chain connectivity |
GET /bridge/limits | Current fee basis points, minimum amounts, and minimum fees |
GET /bridge/fee-quote | Quote the current output and fee for a direction, token, and amount |
GET /bridge/status | Track an operation by origin transaction hash or bridge identifier |
GET /bridge/history | Retrieve same-wallet bridge history (requires address; not a global index) |
GET /explorer/transfers | Public paginated bridge-in or bridge-out transfer list |
GET /explorer/transfers/:id | Public transfer detail by operation id |
GET /explorer/transfers/by-tx/:txHash | Public transfer detail by origin or destination tx hash |
GET /explorer/flows | Per-token inflow vs outflow totals (window=24h|7d|all) |
POST /bridge/xcn-withdraw-intent | Register a signed native-XCN withdrawal intent |
POST /bridge/xcn-withdraw-intent/bind-origin | Bind an intent to its Onyx execution transaction |
The exact request and response schemas are deployed behavior. Inspect responses in a non-production client and handle unknown fields or statuses defensively.
Public explorer namespace (/explorer/*)
Read-only projection of bridge_operations for explorers such as Onyx Scan. No admin, retry, float, signer, lock, or recovery fields are returned.
Direction / flow
| Meaning | direction | flow |
|---|---|---|
| Bridge-in / token inflow to Onyx | ETHEREUM_TO_GOLIATH | in |
| Bridge-out / token outflow from Onyx | GOLIATH_TO_ETHEREUM | out |
List: GET /explorer/transfers?direction=ETHEREUM_TO_GOLIATH|GOLIATH_TO_ETHEREUM or flow=in|out, plus limit / offset pagination.
Detail fields: operationId, direction, flow, status, token, decimals, amountUnit (atomic), amountAtomic / amountFormatted, fee (or null), outputAmount*, inflowAtomic / outflowAtomic, parties, chain ids, origin/destination tx hashes, timestamps, explorerLinks, gasUsed, error.
gasUsed policy (v1): always null. The bridge database has no mined gas-used column. Never treat attempt gas_limit as gas used. UI should hide the field until a real receipt value exists.
Explorer links
| Hash shape | Link |
|---|---|
Ethereum-side 0x | https://etherscan.io/tx/<hash> (explorerLinks.ethereum) |
Onyx-side 0x | https://onyxscan.org/tx/<hash> (explorerLinks.onyxEvm) |
| Onyx native transaction id / consensus timestamp | https://validators.onyx.org/mainnet/transaction/<id> (explorerLinks.onyxNative) |
Onyx native transaction ids must not be labeled as Etherscan links.
Deprecated keys: responses still include two older alias keys, onyx and the legacy native-id key, with values identical to onyxEvm and onyxNative. They will be removed on 2026-11-07. Read only ethereum, onyxEvm, and onyxNative.
Flows: GET /explorer/flows?window=24h|7d|all returns per-token (XCN, ETH, USDC) { inflowAtomic, inflowFormatted, outflowAtomic, outflowFormatted, decimals, transferCountIn, transferCountOut } for COMPLETED operations only (default). Amounts include amountUnit: "atomic" and explicit decimals.
Non-goals: TVL, unique users, operator float, admin/retry boards. Do not use GET /bridge/history as a global transfer index — it requires a wallet address.
Read-only smoke checklist (after an authorized deploy)
bash
# Bridge-in list
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/transfers?flow=in&limit=5' | jq '{count:(.transfers|length), flow:.transfers[0].flow, token:.transfers[0].token}'
# Bridge-out list
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/transfers?direction=GOLIATH_TO_ETHEREUM&limit=5' | jq '{count:(.transfers|length), flow:.transfers[0].flow}'
# Detail by operation id (replace ID)
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/transfers/<operationId>' | jq '{operationId, gasUsed, explorerLinks, fee}'
# Detail by tx hash (replace HASH)
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/transfers/by-tx/<HASH>' | jq '{operationId, originTxHash, destinationTxHash}'
# Per-token inflow / outflow
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/flows?window=24h' | jq .
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/flows?window=7d' | jq .
curl -sS 'https://bridgeapi.onyx.org/api/v1/explorer/flows?window=all' | jq .Confirm gasUsed is null, no admin keys appear in JSON, and wallet history still requires address.
Live discovery example
bash
curl -sS https://bridgeapi.onyx.org/api/v1/bridge/limits | jq .
curl -sS https://bridgeapi.onyx.org/api/v1/health | jq '{status,operational,database}'Never copy the returned fee or minimum into a long-lived build. Fetch again before a user confirms a transfer.
Status handling
Continue polling while the operation is non-terminal. Display the API's maintenance, confirmation, hold, retry, failure, and completion state without manufacturing a destination hash. A completed operation should include the destination proof expected by your integration before you credit or reconcile it.
The native-XCN intent response contains the current transfer destination. It is an operator-controlled value and must not appear as a constant in application code or documentation.