Introduction

Route trades across every eligible liquidity source and choose from ranked executable candidates.

The Router API fans your request across every eligible source - direct DEX liquidity, the RFQ venue, bridges, issuers, fiat rails - and returns ranked executable candidates with a recommendation. “Eligible” is your call: venues are enabled per workspace, and a source you switched off never appears.

Where It Fits

• The broadest coverage - the long tail the RFQ venue deliberately doesn’t chase
• Ranked candidates with a recommendation, and one source down never suppresses the others
• One-signature cross-chain UX - route selection, bridging, and settlement are the candidate’s problem

Sources Behind the Ranking

• Direct DEX liquidity, priced from on-chain state
• Programmable liquidity - a maker quote and a DEX leg in one candidate (rolling out)
• Composite routes - multi-leg, with recovery when a leg parks
• Tokenized-asset venues and fiat corridors (rolling out)

Quick Reference

Facet
Protocol	REST over HTTPS
Credential	API key (X-API-Key header)
Signature	EIP-712 over the escrow-v0 payload
Landing the tx	apiSubmit (TetraFi) or walletBroadcast (you), per candidate
Guarantee	Printed on each candidate: firmness, atomicity, settlement, fees
Effort	Moderate: pick a candidate, preflight it, sign

The Trade Flow

Each candidate’s executionMode says who lands the transaction; preflight returns its nextActions (Execution Modes).

#	Move	Input	Output
1	Collect candidates	Intent (inputs, outputs) → POST /api/v1/router/quotes	Ranked candidates + recommendation
2	Preflight the pick	Selected quote → POST /api/v1/router/orders/preflight	nextActions execution plan
3	Authorize	EIP-712 escrow-v0 payload → taker wallet	Signature
4	Hand it over	Signed order → POST /api/v1/router/orders	Order ID
5	Watch it land	Order ID → GET /api/v1/router/orders/{id} or WebSocket	Status: settled

Candidates settling through an external venue or bridge are walletBroadcast: step 2 returns the transaction and you send it from your own RPC.

Guarantees, Stated Per Candidate

Every candidate states its own terms, and the ranking compares them net of gas and explicit fees:

Field	Description
preview.outputs	What you receive if this candidate executes as quoted
validUntil	The candidate is executable until this timestamp
composite	Present when the candidate is a multi-leg planner route
integrityChecksum	Binds the quote you sign to the quote you were shown

A candidate filled by the RFQ venue keeps RFQ-grade firmness; a multi-leg bridge route states its own settlement model. Rely on what is printed, never on a source label.

Endpoint Map

Endpoint	Purpose
POST /api/v1/router/quotes	Request ranked candidates across eligible sources
POST /api/v1/router/orders/preflight	Check submit-readiness and get nextActions
POST /api/v1/router/orders	Submit a signed order for settlement
GET /api/v1/router/orders/{id}	Track order and settlement status

POST /api/v1/quotes and /api/v1/orders/* remain as temporary aliases and emit deprecation metadata. New integrations target /api/v1/router/*.

Next: the Quickstart, and the allowance groundwork under Token Approvals.