@@ -5,11 +5,11 @@ description: "Learn how to integrate the Trails API for cross-chain transactions
55
66## Welcome to the Trails API
77
8- The Trails API enables seamless cross-chain token swaps, bridges, and payments . This guide walks you through the complete flow from requesting a quote to executing a transaction.
8+ The Trails API enables seamless cross-chain token swaps, deposits, payments, and smart contract executions . This guide walks you through the complete flow from requesting a quote to executing a transaction.
99
1010## Core Workflow
1111
12- Every cross-chain transaction follows this four-step process:
12+ Every interaction through Trails follows this four-step process:
1313
1414``` mermaid
1515flowchart LR
@@ -23,14 +23,13 @@ flowchart LR
2323Request a quote to see rates, fees, and routing options for your transaction.
2424
2525``` typescript
26- const = await fetch (' https://api. trails.sequence.app/rpc/Trails/QuoteIntent'
26+ const = await fetch (' https://trails-api .sequence.app/rpc/Trails/QuoteIntent'
2727 method: ' POST'
2828 headers: {
2929 ' Content-Type' ' application/json'
30- ' X-Access-Key' ' YOUR_ACCESS_KEY'
3130 },
3231 body: JSON .stringify ({
33- ownerAddress: ' 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
32+ ownerAddress: ' 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' // sender address
3433 originChainId: 1 , // Ethereum
3534 originTokenAddress: ' 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC
3635 originTokenAmount: 100000000 , // 100 USDC (6 decimals)
@@ -57,7 +56,7 @@ console.log('Quote received:', {
5756
5857** Key Parameters:**
5958
60- - ** ownerAddress** : Your wallet address
59+ - ** ownerAddress** : User's sender address
6160- ** originChainId** & ** destinationChainId** : Source and destination chains
6261- ** originTokenAddress** & ** destinationTokenAddress** : Token contracts
6362- ** originTokenAmount** : Amount to swap (in token's smallest unit)
@@ -69,14 +68,13 @@ Use `EXACT_INPUT` when you know how much you want to spend, and `EXACT_OUTPUT` w
6968
7069### Step 2: Commit the Intent
7170
72- Lock in the quote by committing the intent. This reserves the rates and generates an intent ID .
71+ Lock in the quote by committing the intent from the previous response which will reserve the rates .
7372
7473``` typescript
75- const = await fetch (' https://api. trails.sequence.app/rpc/Trails/CommitIntent'
74+ const = await fetch (' https://trails-api .sequence.app/rpc/Trails/CommitIntent'
7675 method: ' POST'
7776 headers: {
7877 ' Content-Type' ' application/json'
79- ' X-Access-Key' ' YOUR_ACCESS_KEY'
8078 },
8179 body: JSON .stringify ({ intent })
8280});
@@ -99,24 +97,23 @@ Now we can execute the intent. First, send tokens to the intent address then cal
9997const = await walletClient .sendTransaction ({
10098 to: intent .depositTransaction .toAddress ,
10199 value: 0n ,
102- data: encodeERC20Transfer (
100+ data: encodeERC20Transfer ( // Use your favorite library such as viem to encode if ERC20 transfer
103101 intent .depositTransaction .tokenAddress ,
104102 intent .depositTransaction .toAddress ,
105103 intent .depositTransaction .amount
106104 )
107105});
108106
109- // Wait for transaction confirmation
107+ // Wait for transaction confirmation using viem
110108const = await publicClient .waitForTransactionReceipt ({
111109 hash: depositTx
112110});
113111
114- // Then execute the intent
115- const = await fetch (' https://api. trails.sequence.app/rpc/Trails/ExecuteIntent'
112+ // Then execute the intent with the deposit transaction hash and intentId
113+ const = await fetch (' https://trails-api .sequence.app/rpc/Trails/ExecuteIntent'
116114 method: ' POST'
117115 headers: {
118116 ' Content-Type' ' application/json'
119- ' X-Access-Key' ' YOUR_ACCESS_KEY'
120117 },
121118 body: JSON .stringify ({
122119 intentId ,
@@ -130,51 +127,50 @@ console.log('Execution started:', intentStatus);
130127
131128### Step 4: Monitor Completion
132129
133- Track the transaction status via polling :
130+ Wait for the transaction to complete using the streaming endpoint :
134131
135132``` typescript
136- async function pollForCompletion (intentId : string ) {
133+ async function waitForCompletion (intentId : string ) {
137134 while (true ) {
138- const receiptResponse = await fetch (
139- ' https://api.trails. sequence.app/rpc/Trails/GetIntentReceipt '
135+ const waitResponse = await fetch (
136+ ' https://trails- api.sequence.app/rpc/Trails/WaitIntentReceipt '
140137 {
141138 method: ' POST'
142139 headers: {
143140 ' Content-Type' ' application/json'
144- ' X-Access-Key' ' YOUR_ACCESS_KEY'
145141 },
146142 body: JSON .stringify ({ intentId })
147143 }
148144 );
149145
150- const } = await receiptResponse .json ();
146+ const , done } = await waitResponse .json ();
151147
152148 console .log (' Status:' intentReceipt .status );
153149
154- if (intentReceipt .status === ' SUCCEEDED'
155- console .log (' ✅ Transaction completed!'
156- console .log (' Deposit TX:' intentReceipt .depositTransaction .txnHash );
157- console .log (' Origin TX:' intentReceipt .originTransaction .txnHash );
158- console .log (' Destination TX:' intentReceipt .destinationTransaction .txnHash );
159- return intentReceipt ;
160- }
161-
162- if (intentReceipt .status === ' FAILED'
163- throw new Error (' Transaction failed: ' + intentReceipt .originTransaction .statusReason );
150+ // If done is true, the intent has reached a terminal state
151+ if (done ) {
152+ if (intentReceipt .status === ' SUCCEEDED'
153+ console .log (' ✅ Transaction completed!'
154+ console .log (' Deposit TX:' intentReceipt .depositTransaction .txnHash );
155+ console .log (' Origin TX:' intentReceipt .originTransaction .txnHash );
156+ console .log (' Destination TX:' intentReceipt .destinationTransaction .txnHash );
157+ return intentReceipt ;
158+ } else {
159+ throw new Error (' Transaction failed: ' + intentReceipt .originTransaction .statusReason );
160+ }
164161 }
165-
166- // Wait 2 seconds before next poll
167- await new Promise (resolve => setTimeout (resolve , 2000 ));
162+
163+ // If not done, the endpoint will have waited internally before returning until completion
168164 }
169165}
170166
171- const = await pollForCompletion (intentId );
167+ const = await waitForCompletion (intentId );
172168```
173169
174170## Support
175171
176172Need help? Join our community:
177173
178174- ** Telegram** : [ https://t.me/build_with_trails ] ( https://t.me/build_with_trails )
179- - ** Documentation** : Browse the endpoint references for detailed information
175+ - ** Documentation** : Browse the endpoint references for detailed information and advanced use cases
180176- ** Demo** : Try the [ interactive playground] ( https://demo.trails.build/widget )
0 commit comments