Skip to content

docs: sync api reference 2026-08-31 #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JamesLawton wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: sync api reference 2026-08-31 #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 233 additions & 1 deletion api-reference/before-annotations-trails-api.gen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1780,12 +1780,21 @@
"initTransactionHash": {
"type": "string"
},
"initChainId": {
"type": "number"
},
"fillTransactionHash": {
"type": "string"
},
"fillChainId": {
"type": "number"
},
"refundTransactionHash": {
"type": "string"
},
"refundChainId": {
"type": "number"
},
"edgeTokenMetadata": {
"$ref": "#/components/schemas/TokenMetadata"
},
Expand Down Expand Up @@ -1932,6 +1941,9 @@
"timedRefundUnlockTimestamp": {
"type": "number"
},
"pausableSapientSignerAddress": {
"type": "string"
},
"trailsContracts": {
"$ref": "#/components/schemas/TrailsContracts"
},
Expand Down Expand Up @@ -5049,12 +5061,21 @@
"initTransactionHash": {
"type": "string"
},
"initChainId": {
"type": "number"
},
"fillTransactionHash": {
"type": "string"
},
"fillChainId": {
"type": "number"
},
"refundTransactionHash": {
"type": "string"
},
"refundChainId": {
"type": "number"
},
"transactionStates": {
"type": "array",
"description": "[]TransactionStateInfo",
Expand Down Expand Up @@ -5140,6 +5161,32 @@
}
}
},
"ExecuteIntentEdgeRequest": {
"type": "object",
"required": [
"intentId"
],
"properties": {
"intentId": {
"type": "string"
}
}
},
"ExecuteIntentEdgeResponse": {
"type": "object",
"required": [
"intentId",
"intentStatus"
],
"properties": {
"intentId": {
"type": "string"
},
"intentStatus": {
"$ref": "#/components/schemas/IntentStatus"
}
}
},
"RetryIntentRequest": {
"type": "object",
"required": [
Expand Down Expand Up @@ -7532,7 +7579,8 @@
"tags": [
"Trails"
],
"summary": "",
"summary": "DEPRECATED for new integrations; behaviorally stable for existing ones.",
"description": "New clients call ExecuteIntent directly after QuoteIntent (edge flows arm\nvia ExecuteIntentEdge). Existing callers keep the full legacy contract:\nvalidate, atomically arm origin edge quotes, write QUOTED -> COMMITTED.\n",
"requestBody": {
"content": {
"application/json": {
Expand Down Expand Up @@ -7894,6 +7942,190 @@
}
}
},
"/rpc/Trails/ExecuteIntentEdge": {
"post": {
"operationId": "Trails-ExecuteIntentEdge",
"tags": [
"Trails"
],
"summary": "",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteIntentEdgeRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteIntentEdgeResponse"
}
}
}
},
"4XX": {
"description": "Client error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorWebrpcEndpoint"
},
{
"$ref": "#/components/schemas/ErrorWebrpcRequestFailed"
},
{
"$ref": "#/components/schemas/ErrorWebrpcBadRoute"
},
{
"$ref": "#/components/schemas/ErrorWebrpcBadMethod"
},
{
"$ref": "#/components/schemas/ErrorWebrpcBadRequest"
},
{
"$ref": "#/components/schemas/ErrorWebrpcClientAborted"
},
{
"$ref": "#/components/schemas/ErrorWebrpcStreamLost"
},
{
"$ref": "#/components/schemas/ErrorUnauthorized"
},
{
"$ref": "#/components/schemas/ErrorPermissionDenied"
},
{
"$ref": "#/components/schemas/ErrorSessionExpired"
},
{
"$ref": "#/components/schemas/ErrorMethodNotFound"
},
{
"$ref": "#/components/schemas/ErrorRequestConflict"
},
{
"$ref": "#/components/schemas/ErrorAborted"
},
{
"$ref": "#/components/schemas/ErrorGeoblocked"
},
{
"$ref": "#/components/schemas/ErrorRateLimited"
},
{
"$ref": "#/components/schemas/ErrorProjectNotFound"
},
{
"$ref": "#/components/schemas/ErrorAccessKeyNotFound"
},
{
"$ref": "#/components/schemas/ErrorAccessKeyMismatch"
},
{
"$ref": "#/components/schemas/ErrorInvalidOrigin"
},
{
"$ref": "#/components/schemas/ErrorInvalidService"
},
{
"$ref": "#/components/schemas/ErrorUnauthorizedUser"
},
{
"$ref": "#/components/schemas/ErrorQuotaExceeded"
},
{
"$ref": "#/components/schemas/ErrorQuotaRateLimit"
},
{
"$ref": "#/components/schemas/ErrorNoDefaultKey"
},
{
"$ref": "#/components/schemas/ErrorMaxAccessKeys"
},
{
"$ref": "#/components/schemas/ErrorAtLeastOneKey"
},
{
"$ref": "#/components/schemas/ErrorTimeout"
},
{
"$ref": "#/components/schemas/ErrorInvalidArgument"
},
{
"$ref": "#/components/schemas/ErrorUnavailable"
},
{
"$ref": "#/components/schemas/ErrorQueryFailed"
},
{
"$ref": "#/components/schemas/ErrorIntentStatus"
},
{
"$ref": "#/components/schemas/ErrorIntentProtocolDeprecated"
},
{
"$ref": "#/components/schemas/ErrorNotFound"
},
{
"$ref": "#/components/schemas/ErrorUnsupportedNetwork"
},
{
"$ref": "#/components/schemas/ErrorClientOutdated"
},
{
"$ref": "#/components/schemas/ErrorIntentsSkipped"
},
{
"$ref": "#/components/schemas/ErrorQuoteExpired"
},
{
"$ref": "#/components/schemas/ErrorHighPriceImpact"
},
{
"$ref": "#/components/schemas/ErrorIntentsDisabled"
}
]
}
}
}
},
"5XX": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorWebrpcBadResponse"
},
{
"$ref": "#/components/schemas/ErrorWebrpcServerPanic"
},
{
"$ref": "#/components/schemas/ErrorWebrpcInternalError"
},
{
"$ref": "#/components/schemas/ErrorUnexpected"
},
{
"$ref": "#/components/schemas/ErrorChainNodeHealth"
}
]
}
}
}
}
}
}
},
"/rpc/Trails/RetryIntent": {
"post": {
"operationId": "Trails-RetryIntent",
Expand Down
34 changes: 21 additions & 13 deletions api-reference/endpoints/commit-intent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,18 @@ title: CommitIntent
openapi: ../trails-api.gen.json post /rpc/Trails/CommitIntent
---

<Warning>
**Deprecated for new integrations.** `CommitIntent` remains behaviorally stable for existing callers, but new integrations should call [`ExecuteIntent`](/api-reference/endpoints/execute-intent) directly on a `QUOTED` intent. For a Solana or Tron origin, arm fill monitoring with [`ExecuteIntentEdge`](/api-reference/endpoints/execute-intent-edge) instead.
</Warning>

## Overview

The `CommitIntent` endpoint commits an intent to the Trails system, reserving the quote and preparing it for execution. This is a required step between getting a quote and executing the transaction.
The `CommitIntent` endpoint validates a quoted intent, atomically arms origin edge quotes, and transitions the intent from `QUOTED` to `COMMITTED`. New clients skip this step — `ExecuteIntent` accepts `QUOTED` intents directly and folds in the same validation.

## Use Cases

- Lock in a quote before execution
- Prepare the intent for signing and execution
- Transition from quoted to committed state and preparing a deposit intent address
- Legacy integrations that still separate the commit step from execution
- Preserving compatibility with older SDKs that call `CommitIntent` before `ExecuteIntent`

## Request Parameters

Expand All @@ -27,14 +30,19 @@ The response includes:

## Intent Lifecycle

Legacy flow (existing callers):

```
QuoteIntent → CommitIntent → ExecuteIntent → Receipt
```

The `CommitIntent` step is crucial because it:
1. Reserves the quoted rates
2. Locks in the gas fee estimates
3. Validates the intent parameters
Current flow (new integrations):

```
QuoteIntent → ExecuteIntent → Receipt
```

For Solana/Tron origins, replace `ExecuteIntent` with `ExecuteIntentEdge` to arm fill monitoring before the user pays on the edge chain.

## Example

Expand Down Expand Up @@ -68,17 +76,17 @@ console.log('Intent committed:', intentId);
## Important Notes

<Warning>
Committed intents must be executed within **10 minutes**. Make sure to call `ExecuteIntent` before this window expires, or you'll need to get a new quote and commit again.
Committed intents must be executed within **10 minutes**. Call `ExecuteIntent` before this window expires or the intent will expire and require a fresh quote.
</Warning>

<Info>
The intent object from `QuoteIntent` should not be modified, otherwise the API will reject the commitment.
The intent object from `QuoteIntent` must be forwarded unmodified — the server rejects mutated intents.
</Info>

## Next Steps

After committing an intent:
1. Prepare the transaction signature using the provided intent details for the user to deposit into the intent address
2. Execute the transaction with `ExecuteIntent`
3. Monitor the transaction status with `WaitIntentReceipt`
1. Prepare the transaction signature using the provided intent details for the user to deposit into the intent address.
2. Execute the transaction with [`ExecuteIntent`](/api-reference/endpoints/execute-intent).
3. Monitor the transaction status with [`WaitIntentReceipt`](/api-reference/endpoints/wait-intent-receipt).

Loading
Loading