Skip to main content

Welcome to the Trails API

The Trails API enables seamless cross-chain token swaps, deposits, payments, and smart contract executions in a simplified interface with the Trails protocol.

Authentication

All API requests require an API key passed in the X-Access-Key header.
Get an API key: Sign up and create an API key on the Trails Dashboard

Key Security

An access key used by the widget or any other browser code is public: anyone can read it from your page. Restrict it in the key’s settings on the Trails Dashboard:
  • Allowed origins: list the exact origins that may use the key, for example https://shop.example.com. A request whose Origin header doesn’t match is rejected with InvalidOrigin (code 1103, HTTP 403) before it counts against your limits. An empty list allows every origin.
  • Require origin: reject requests that send no Origin header. Without it, requests without an Origin header (curl, scripts, servers) are accepted even when allowed origins are set.
Set both. Together they stop other websites from using your key from their visitors’ browsers. They do not make a browser key secret: a script outside a browser can send any Origin header it likes. Treat a browser key as public, and rotate it if it is abused. Use separate keys for separate jobs: an origin-restricted key for the widget, and a different key for your server’s API calls, which send no Origin header. You can then restrict and rotate each key on its own. Separate keys do not get separate limits: every key in a project shares the project’s rate limit and usage quota.
Admin API secret keys are for server-side use only. Never put them in a browser, a mobile app or the widget. The API rejects a secret key sent with an Origin header (SecretKeyCorsDisallowed, code 1009, HTTP 403).

Core Workflow

Every interaction through Trails follows this flow:
1

Get Wallet Balance

Before requesting a quote, fetch the user’s token balances using a multichain Indexer to display total available tokens and amounts for the user to select:
2

Get a Quote

Request a quote to see rates, fees, and routing options for your transaction.
Key Parameters:
  • ownerAddress: User’s wallet address
  • originChainId & destinationChainId: Source and destination chains
  • originTokenAddress & destinationTokenAddress: Token contracts
  • originTokenAmount: Amount to swap (in token’s smallest unit)
  • tradeType: EXACT_INPUT (specify input) or EXACT_OUTPUT (specify output)
Use EXACT_INPUT when you know how much you want to spend, and EXACT_OUTPUT when you know exactly how much you need to receive.
3

(Legacy) Commit the Intent

CommitIntent is deprecated for new integrations. New integrations skip this step and call ExecuteIntent directly on the quoted intent — ExecuteIntent accepts QUOTED intents and folds in the same validation CommitIntent used to perform. Existing callers may still commit before executing.
The intent object contains everything needed to execute the intent and the server rejects mutated payloads, so pass it back unchanged.
Quotes expire 15 minutes after being issued. Call ExecuteIntent (or ExecuteIntentEdge for Solana/Tron origins) within this window, or request a new quote. Committing first does not extend the window; legacy callers still share the same 15-minute quote expiry.
4

Execute the Transaction

Execute the intent using one of two mutually exclusive methods - either a normal transfer to the intent address or a permit operation if a user wants to pay in a non-native gas token:
Send tokens to the intent deposit address, then call ExecuteIntent with the transaction hash:
5

Monitor Completion

Wait for the transaction to complete using the streaming endpoint:
Now you have an end to end API integration with Trails for seamless chain abstraction flows! You can continue this initial integration for specific use cases such as:
  • x402 Payments
  • AI Agents
  • Server-side currency conversion & settlement
  • Fund, Swap, Earn, or Pay for any application
  • Pass in optional calldata to call any smart contract function

Intent Statuses

SUCCEEDED, FAILED, ABORTED, INVALID and REFUNDED are final: WaitIntentReceipt returns done: true for each of them. When an intent doesn’t succeed, the receipt’s statusReason says why.
A status records what happened; it doesn’t move funds. FAILED, ABORTED and INVALID don’t mean the user’s funds were returned. Funds that reached the intent wallet stay there until a refund or a recovery moves them. See Refunds & Recovery.

Error Handling

The API returns errors in a consistent JSON format:

Error Codes

Handling Errors

Quote Expiration

Quotes have strict time limits:
Always check quote expiration before executing. The intent.expiresAt timestamp is the single deadline for calling ExecuteIntent (or ExecuteIntentEdge), whether or not you committed first.

Rate Limiting

Limits apply per project, not per key. Every access key in a project, and every user’s browser running the widget with one of those keys, draws from the same two budgets: The values depend on your project’s plan. Upgrade the project in the Trails Dashboard or contact the Trails team to raise them.
  • Every Trails API method costs 1 request, QuoteIntent included. There is no separate QuoteIntent limit.
  • A request rejected by the per-minute limit isn’t counted. A request that passes it counts toward the usage quota, even if the API then returns an error such as InvalidArgument.
  • Using several keys doesn’t add capacity: they share the project’s limits.
  • Requests sent without an access key fall under a public limit applied per IP address and fail with RateLimited (code 1007, HTTP 429). That limit is separate from your project’s limits.
Responses to requests made with an access key carry these headers: Best practices:
  • On HTTP 429 (codes 1201 and 1007), wait for Retry-After before retrying instead of retrying immediately
  • Don’t retry QuotaExceeded (code 1200, HTTP 423): it lasts until the next billing cycle or a plan upgrade
  • Cache GetChains, GetTokenList responses (they change infrequently)
  • Batch balance checks where possible
  • Choose a limit that covers peak traffic: requests from all of your users’ browsers count against it

Next Steps

Explore additional endpoints to enhance your integration:

Transaction Management

  • GetIntent - Retrieve full intent details including quote, fees, and status
  • GetIntentReceipt - Poll for transaction status and get receipt with transaction hashes
  • WaitIntentReceipt - Stream intent updates with automatic polling until completion
  • GetIntentHistory - Get complete transaction history with receipts for a user’s wallet address

Earn

Support

Need help? Join our community: