Skip to main content
Use these endpoints to track the state of an intent after execution and to query historical payment data. For authentication and base URL, see the API overview.

​
GetIntent

Retrieve the current status and full details of an intent. Endpoint: POST /GetIntent

​
Request parameters

FieldTypeRequiredDescription
intentIdstringYesThe intent ID to look up

​
Response fields

FieldDescription
intentThe full intent object including current status
intent.statusOne of QUOTED, COMMITTED, EXECUTING, SUCCEEDED, or FAILED

​
Example

const { intent } = await trails.getIntent({ intentId });

console.log("Status:", intent.status);

​
GetIntentReceipt

Get the transaction hashes and settlement status for a completed intent. Use this to confirm that funds arrived at the destination. Endpoint: POST /GetIntentReceipt

​
Request parameters

FieldTypeRequiredDescription
intentIdstringYesThe intent ID to retrieve the receipt for

​
Response fields

FieldDescription
statusSUCCEEDED or FAILED
transactionHashTransaction hash on the destination network
originTransactionHashTransaction hash on the source network

​
Example

const receipt = await trails.getIntentReceipt({ intentId });

if (receipt.status === "SUCCEEDED") {
  console.log("Settled on destination:", receipt.transactionHash);
  console.log("Source transaction:", receipt.originTransactionHash);
}

​
WaitIntentReceipt

Long-poll until an intent reaches a terminal state (SUCCEEDED or FAILED). The API holds the connection open and responds as soon as the intent settles. Endpoint: POST /WaitIntentReceipt

​
Request parameters

FieldTypeRequiredDescription
intentIdstringYesThe intent ID to wait on

​
Response fields

FieldDescription
intentReceiptThe receipt object, same structure as GetIntentReceipt
donetrue when a terminal state has been reached
Use WaitIntentReceipt when you want to block until settlement, for example in a server-side payout flow where the next step depends on confirmed settlement. Use GetIntentReceipt polling when you need to check status periodically without holding a connection open.

​
Example

const { intentReceipt, done } = await trails.waitIntentReceipt({ intentId });

if (done && intentReceipt.status === "SUCCEEDED") {
  // Funds have settled; continue with your post-settlement logic
  console.log("Settlement confirmed:", intentReceipt.transactionHash);
}

​
SearchIntents

Find intents by owner address or transaction hash. Useful for looking up an intent when you have the source transaction hash but not the intent ID. Endpoint: POST /SearchIntents

​
Request parameters

FieldTypeRequiredDescription
ownerAddressstringNoFilter by the customer’s wallet address
transactionHashstringNoFilter by a source or destination transaction hash
pagenumberNoPage number for pagination; starts at 1
pageSizenumberNoNumber of results per page
At least one of ownerAddress or transactionHash is required.

​
Response fields

FieldDescription
intentsArray of intent objects matching the query

​
Example

const { intents } = await trails.searchIntents({
  ownerAddress: "0xCUSTOMER_ADDRESS",
  page: 1,
  pageSize: 20,
});

intents.forEach((intent) => {
  console.log(intent.intentId, intent.status);
});

​
GetIntentHistory

Retrieve paginated intent history with receipts for a given address. Returns settled and in-progress intents together with their receipt data where available. Endpoint: POST /GetIntentHistory

​
Request parameters

FieldTypeRequiredDescription
ownerAddressstringYesThe customer’s wallet address
pagenumberNoPage number; starts at 1
pageSizenumberNoNumber of results per page

​
Example

const history = await trails.getIntentHistory({
  ownerAddress: "0xCUSTOMER_ADDRESS",
  page: 1,
  pageSize: 50,
});

history.intents.forEach((entry) => {
  console.log(entry.intent.intentId, entry.intent.status, entry.receipt?.transactionHash);
});