Route / developers
Download Markdown ↓

Auto-route

For execution after route selection, use the durable worker recipe. Auto-route is discovery/ranking; it grants no wallet authorization and does not replace payment signing and tracking.

Auto-route compares direct paths and paths of up to three steps for an application's payment intent. TypeSafe interprets the optimization preference; Route discovers exact asset paths, requests provider quotes, checks the owner policy and API-key restrictions, and ranks the eligible results using deterministic arithmetic.

Auto-route is optional. Standard quotes keep their existing behavior and price. Mainnet keys with quotes:write can use either POST /v1/auto-route or POST /v1/quotes with an autoRoute object. Testnet does not expose Auto-route.

Request#

Resolve both asset IDs from GET /v1/assets. For Bitcoin to native Stellar USDC, select the exact BTC and native USDC entries; a symbol alone is not sufficient.

{
  "sourceAssetId": "<Bitcoin BTC catalog ID>",
  "destinationAssetId": "<Stellar native USDC catalog ID>",
  "amount": "0.001",
  "slippageBps": 10,
  "autoRoute": {
    "intent": "Minimize total cost while receiving native USDC on Stellar"
  }
}

Send the project API key, Route-Network: mainnet, and a UUID Idempotency-Key. The key selects the project and owner policy. Replaying identical input with the same idempotency key returns the saved quote without another evaluation or charge. Changing the intent or routing mode requires a new idempotency key.

Responses default to view=best: one recommendation with received amount, minimum, estimated USD cost, cost completeness, transfer count, status and expiry. Use ?view=list for ranked alternatives that can proceed to preparation, ?view=compact for all candidates and checks, or ?view=full for detailed evaluation, pricing, gas and provider evidence. Changing views does not re-evaluate or charge for the saved quote; reading it never creates a payment.

The preference is limited to 500 characters. Describe lowest cost, fastest arrival, highest recipient amount, or balanced. Assets, amount, provider allowlists, USD limits and delivery limits are structured constraints; prose cannot override them. A simple transfer description without an optimization preference uses the policy's default priority. Ambiguous or contradictory preferences return AUTO_ROUTE_CLARIFICATION_REQUIRED (422).

The preference and bounded quote evidence are sent to TypeSafe. Evidence includes exact asset identities, networks, amounts, owner limits, each leg's minimum output, fee components and completeness, scoped timing, capacity observations, quote expiry, USD-price freshness and released builder support. The context includes up to 32 candidates within a 14,000-byte evidence budget, with eligible and quoted candidates first; it discloses truncation. Detailed fee lists are capped at 16 components and gas lists at eight observations, with original totals retained. These context limits do not reduce Route's deterministic candidate comparison. Route does not send API keys, account identifiers, wallet addresses, raw provider payloads or signing material as evaluation fields. Do not put private information in the preference. The evaluation model is pinned to jev-1.13.0; compact and full retain its version, objective and confidence. view=full also exposes probabilities and evidenceVersion: route-evidence-v4. The context states whether the intermediate search completed; it does not include the search notes. Confidence describes intent interpretation, not payment reliability.

TypeSafe interprets the preference. Route performs path discovery, fee arithmetic, eligibility checks, ranking and execution. A structured lowest-cost request can use standard routing without TypeSafe. Giving the model more evidence does not create missing provider execution support or make unknown fees known.

Path discovery and selection#

The search includes direct provider paths and paths through at most two verified intermediate assets, retaining up to three first-leg alternatives per intermediate by minimum output. Defaults are native USDC on the first two applicable networks from Base, Arbitrum and Ethereum. Both endpoint networks are excluded as intermediates. Set autoRoute.intermediateAssetIds to up to two verified catalog IDs to choose different intermediates; an empty array requests direct paths only.

Set autoRoute.maxLegs: 3 to also search both ordered pairs of the two intermediate assets. The default remains 2. Three-leg search retains at most one second-leg alternative per retained first leg; compact and full disclose these bounds. Each route uses distinct network nodes. Three-step search needs two intermediates: when only one applies, for example the default for a payment between two of Base, Arbitrum and Ethereum, only direct and two-step paths are searched, autoRoute.search.secondLegsPerFirst is null and autoRoute.search.notes says so.

Set autoRoute.requoteSlippageBps to explicitly allow later quotes to move below the final quoted minimum: 10 means 0.1%, 50 means 0.5%, and 100 means 1%. It defaults to 0 and accepts integers from 0 to 1,000. This is an additional allowance beyond each provider’s slippageBps, applied once to the multi-step route, never to every leg or every refresh. Direct routes are unchanged.

For example, a final quoted minimum of 4.853381 USDC with a 0.1% allowance produces a displayed minimum of 4.848528 USDC (rounded up to the asset’s precision). The candidate’s minimumReceived is this adjusted floor; in view=full, details.quotedMinimumReceived and details.requoteSlippageBps disclose its basis. Preparation saves the displayed minimum, or a higher caller-specified minimum. Every later authorization must preserve it. Changing the allowance requires a fresh quote; it cannot lower an existing payment’s commitment. Missing fee evidence, fee limits and quote expiry still block execution.

Every later leg is quoted using the exact minimum output of its preceding leg. Asset identity, issuer/contract, network and precision must match at the handoff. All involved Route adapters must be enabled and allowed by the owner policy and key. An aggregator's underlying provider list remains disclosed under that adapter's own integration rules.

This is a bounded search, not an exhaustive or globally optimal routing guarantee. An intermediate may be unavailable, restricted or illiquid. Two-step routing may cost more than a direct provider path; an unnecessary intermediate is not preferred.

In compact/full, autoRoute.search.notes records what happened to each intermediate leg: a provider quote that was unavailable, with the provider's reason, a failed leg request, a missing intermediate USD price, and legs excluded by provider rules, API-key restrictions or provider coverage. autoRoute.search.complete is false when a provider could not quote a searched leg or a leg request failed. Composed paths through that leg were not compared, so a missing multi-step path does not mean none exists; decision.explanation says so. Unsupported pairs, paused providers and excluded legs do not make the search incomplete, and neither does an unavailable provider that a matching provider rule excludes from that leg.

The compact and full views retain the previous quote shape:

  • selected: the best policy-eligible quote for the interpreted preference, or null.
  • executionSelection.candidateId: the best eligible candidate that also has released execution support, or null.
  • preparationSelection: the ordered choices that can proceed to wallet preparation. A source-gas-only gap can appear here with provisional: true, without becoming a fully eligible recommendation. The order follows the interpreted objective; incomplete costs may change it after preparation.
  • autoRoute: interpretation summary, search bounds, completeness and notes, selected candidate and creditMultiplier: 4. Full evaluation evidence is available with view=full.
  • candidates[].composition: the ordered intermediate assets and all quote legs, including fees, minimum receipt, expiry and timing scope.

Cost minimizes estimated total USD cost. Return maximizes minimum recipient USD value (all candidates have the same final asset). Speed requires comparable complete arrival estimates, which exist only for modeled direct paths; composed paths are never ranked by speed. Speed and balanced results include autoRoute.warnings with that coverage and the arrival model's review expiry. Balanced uses ordinal ranks weighted 50% cost, 30% complete arrival and 20% number of transfers; missing complete timing receives the worst timing rank. Ties favor fewer transfers, then stable candidate identity. These preferences never make an excluded or incomplete candidate eligible. The policy's own requirements, including evidence required by a speed policy, still apply.

Missing gas, stale prices or incomplete arrival estimates stay explicit. In view=full, observedCostRank can help inspect partial results, but it is not an authorization or a fully validated recommendation. Adding partial estimates together does not establish a complete arrival time: intermediate wallet authorization and waiting remain additional.

Gas and wallet readiness#

Gas evidence, available with view=full, includes the native currency and separate execution, rollup data-posting and operator components where applicable. Bitcoin and classic Stellar payments report their network component. These components explain the gas total; they are not additional fees. The model receives component amounts, the current estimate time and the age and confidence of any historical execution sample.

For quiet OFT paths, a verified reference up to seven days old can be repriced using current gas and rollup fee oracles, after unchanged source/token runtime and EIP-1967 implementation checks. It is marked referenceOnly: true, low confidence, with a 100% budgeting margin. This does not establish a current delivery time or wallet readiness. Read the complete gas evidence rules.

For NEAR paths funded with native BTC, the comparison includes a Bitcoin network-fee model: 250 virtual bytes for up to two single-key native SegWit/Taproot inputs, a standard deposit output and change, multiplied by the current two-block fee-rate estimate plus 25%, rounded up to a whole satoshi per virtual byte. This is a low-confidence comparison budget, not a confirmation-time guarantee or a fee ceiling for fragmented wallets. The gas observation reports basis: utxo-model, transactionVbytes, feeRateSatVbyte and estimatedAt. Failed network identity or fee-rate checks leave the fee unknown. Actual confirmed inputs and the transaction fee are revalidated at preparation and signing.

Quote evaluation does not establish account balances, spending approvals or gas funding. These are explicitly marked as unverified in the model context. Additional transfers to fund an intermediate wallet are not included in the quoted transfer costs; arrange them within a separate budget and verify them before execution. Route does not currently offer general EVM gas sponsorship.

Execute a selected path#

Use sdk.startPayment(input, {quoteRequestId, paymentRequestId}) with autoRoute in the quote input to request a recommendation, create its payment and retrieve the next required action. Save both UUIDs first; reuse identical input and IDs after a timeout. For separate calls, accept the saved recommendation with POST /v1/payments and {mode: "prepare", quoteId}, or acceptQuote(quoteId, paymentRequestId). Include candidateId to choose an alternative returned by view=list. Route checks the saved choice again and refuses if it is no longer usable; it never silently switches routes. requires-fee-confirmation still needs source gas validation. See the customer API example. Quote discovery itself never creates a payment; the SDK helper explicitly accepts it and stops at the next action without signing or submitting.

Direct supported paths use their existing preparation and wallet-action flow. Supported two- or three-step paths use the composed payment workflow:

  1. Provide source, recipient and customer-controlled intermediate wallets.
  2. Prepare and authorize the first transfer.
  3. Wait for verified, finalized intermediate delivery.
  4. Call advance to obtain a fresh next-leg quote for the actual received amount.
  5. Recheck the final minimum, combined fee budget, provider permissions and wallet readiness, then separately authorize the next transfer. Repeat for a third leg when present.

Executable composed paths currently require a released builder and receipt verifier for every leg, with every intermediate wallet on Ethereum, Base or Arbitrum. The intermediate wallet needs its own native gas asset. Supported SwapKit simple deposits can participate in execution. Garden legs are excluded while the platform pause is active. Unsupported SwapKit transaction types and unsupported intermediate networks remain quote-only. A three-leg discovery result does not expand an adapter’s execution coverage.

The transfers are not atomic. A later-leg quote does not reserve its price or liquidity. If a later leg cannot satisfy the saved minimum or owner policy, the intermediate asset remains in the customer wallet for recovery. Do not automatically create or fund a replacement when a signed/submitted action is unresolved.

Credits and errors#

Auto-route uses 4× standard credits: 4 credits for a comparison with an eligible recommendation and 40 credits for a verified completed logical payment. The 40-credit hold begins at preparation and is consumed once after completion, including all legs. Internal quotes, tracking and retries do not add charges. Dashboard-origin comparisons and testnet remain free under the billing rules.

Failed evaluations, unclear intent and comparisons without an eligible recommendation do not consume comparison credits. A successful comparison charge remains if its payment is later abandoned. Insufficient credits returns INSUFFICIENT_CREDITS (402). TypeSafe failure returns AUTO_ROUTE_UNAVAILABLE (503); Route does not silently charge for a standard-quote fallback. Request a standard quote explicitly if desired.

Missing historical source-gas evidence can be resolved during wallet preparation. TypeSafe receives preparation eligibility and the deferred source-gas check separately from full quote eligibility. It cannot approve spending, waive limits or invent a fee. For composed paths, every remaining leg’s preview budget must already be complete; actual fees are checked again before each signature. The added preparation selection does not change comparison billing: a comparison without a fully eligible recommendation remains uncharged under the existing rules.

Bitcoin is not a supported intermediate wallet in the composed-payment API.

Asset-specific provider rules are mandatory for the overall payment and each leg. TypeSafe cannot override a required provider or CCTP mode. Before the bounded search ranks alternatives, it removes every leg that a matching whole-payment or leg rule disallows, so cheaper disallowed legs cannot crowd out a compliant path.