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 theX-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 whoseOriginheader doesn’t match is rejected withInvalidOrigin(code 1103, HTTP 403) before it counts against your limits. An empty list allows every origin. - Require origin: reject requests that send no
Originheader. Without it, requests without anOriginheader (curl, scripts, servers) are accepted even when allowed origins are set.
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.
Core Workflow
Every interaction through Trails follows this flow:1
2
Get a Quote
Request a quote to see rates, fees, and routing options for your transaction.- 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) orEXACT_OUTPUT(specify output)
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.intent object contains everything needed to execute the intent and the server rejects mutated payloads, so pass it back unchanged.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:- Transfer Flow
- Alternative Fee Token Flow
Send tokens to the intent deposit address, then call
ExecuteIntent with the transaction hash:Setup: Instantiate viem
Setup: Instantiate viem
- 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.
Error Handling
The API returns errors in a consistent JSON format:Error Codes
Handling Errors
Quote Expiration
Quotes have strict time limits: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,
QuoteIntentincluded. There is no separateQuoteIntentlimit. - 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.
Best practices:
- On HTTP 429 (codes 1201 and 1007), wait for
Retry-Afterbefore 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,GetTokenListresponses (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
Discovery & Search
- SearchIntents - Search and filter intents by status, user, chain, or date range
- GetTokenPrices - Get current USD prices for tokens to display values in your UI
- GetChains - Get list of supported chains
- GetTokenList - Get available tokens for specified chains
- GetExactInputRoutes - Find destination tokens from a source token
- GetExactOutputRoutes - Find source tokens that route to a destination
Earn
- YieldGetMarkets - List and filter DeFi markets (Aave, Morpho, Yearn) with APY and TVL
- YieldGetProviders - List available yield protocols
- YieldGetAggregateBalances - Fetch a wallet’s active yield positions across chains
- YieldCreateEnterAction - Generate deposit calldata for a yield market
- YieldCreateExitAction - Generate withdrawal calldata from a yield position
Support
Need help? Join our community:- Telegram: https://t.me/build_with_trails
- Documentation: Browse the endpoint references for detailed information and advanced use cases
- Demo: Try the interactive playground