Routing & events

Routing (V2)

Given a recipient, asset, and objective, the route engine resolves the recipient's disclosed endpoints, scores compatible candidates against live network telemetry, and recommends the best route plus ranked alternatives.

The One Rule

Route recommendation is the Google Maps for money. Settla picks the route; it never drives the car. Amounts and fees are routing context only, never charges, and no recommendation is ever stored. Every response carries an explicit disclaimer field saying so.

POST/v1/recommend-route

Requires scope recommend_route (or *). The engine calls the resolver with your credentials, so it only ever scores endpoints you are authorized to see — privacy and consent are enforced upstream and never bypassed.

Request body

Field	Type	Description
`to`required	`string`	The recipient alias or identity, e.g. `@john`.
`asset`required	`string`	Asset to send, e.g. `USDC`, `USD`.
`network`optional	`string`	Constrain to a network, or `any` (default) to consider all.
`amount`optional	`string`	Routing context only (affects fee estimation and min/max capability filtering). Never a charge.
`objective`optional	`string`	`fastest` · `lowest_fee` · `preferred` · `most_reliable` · `most_compatible`. Defaults to the recipient's route policy objective, else `preferred`.
`constraints`optional	`object`	Optional: `allowed_networks` (hard filter), `preferred_networks` (soft bonus), `exclude_endpoint_types`, `max_fee_usd`, `max_settlement_seconds`, `min_reliability`.

Example

curl https://api.settla.network/v1/recommend-route \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "@john",
    "asset": "USDC",
    "network": "any",
    "amount": "100.00",
    "objective": "lowest_fee"
  }'

Response

{
  "to": "idn_2x9...",
  "asset": "USDC",
  "objective": "lowest_fee",
  "recommended_route": {
    "endpoint": "end_a1...",
    "endpoint_type": "crypto_wallet",
    "network": "polygon",
    "rail": "onchain",
    "asset": "USDC",
    "reason": "lowest_fee",
    "score": 0.94,
    "est_fee_usd": "0.01",
    "est_seconds": 5,
    "reliability": 0.99
  },
  "alternatives": [
    { "network": "base", "rail": "onchain", "reason": "most_reliable",
      "score": 0.88, "est_fee_usd": "0.02", "est_seconds": 3, "reliability": 0.99 }
  ],
  "disclaimer": "Settla recommends routes; it never moves, holds, or settles funds.",
  "livemode": false,
  "request_id": "req_..."
}

The engine normalizes est_fee_usd, est_seconds, and reliability to a 0–1 scale from network telemetry, takes a weighted sum by objective (or the recipient's route-policy weights), applies hard constraints, and ranks deterministically. Higher score is better.

Objectives & reason codes

Objective	Optimizes for
lowest_fee	Minimum estimated fee.
fastest	Minimum estimated settlement time.
most_reliable	Highest observed reliability.
most_compatible	Broadest asset/network compatibility for the recipient.
preferred	Recipient's preferred networks / route policy bias.

Each route carries a machine-readable reason code: lowest_fee, fastest, most_reliable, most_compatible, preferred, or only_option (when a single compatible candidate exists).

Route policies

A recipient can persist a default routing preference (objective, weights, constraints, preferred networks). When the request omits an objective, the engine falls back to this policy.

POST/v1/route-policies

GET/v1/identities/:id/route-policies

PATCH/v1/route-policies/:id

DELETE/v1/route-policies/:id

Scope: routes:write.

Errors

Status	Code	When
404	recipient_not_found	Resolution disclosed no endpoints for the recipient.
422	no_compatible_route	No disclosed capability matches the asset/network/constraints.
403	permission_error	Key lacks the recommend_route scope.