Skip to main content
POST
/
rpc
/
Trails
/
PrepareIntentRecovery
cURL
curl --request POST \
  --url https://trails-api.sequence.app/rpc/Trails/PrepareIntentRecovery \
  --header 'Content-Type: application/json' \
  --data '
{
  "intentId": "<string>",
  "intentAddress": "<string>",
  "refundToAddress": "<string>",
  "tokenAddress": "<string>"
}
'
{
  "intentId": "<string>",
  "intentAddress": "<string>",
  "chainId": 123,
  "intentSource": "<string>",
  "payload": {},
  "typedData": {},
  "payloadHash": "<string>",
  "recoveryTokens": [
    {
      "contractAddress": "<string>",
      "balance": "<string>",
      "balanceUsd": "<string>",
      "priceUsd": "<string>",
      "decimals": 123,
      "chainId": 123,
      "symbol": "<string>"
    }
  ]
}

​
Overview

The PrepareIntentRecovery endpoint returns a backend-prepared payload and typed data that the user signs to recover funds stranded in an intent wallet. Combined with BuildIntentRecoveryTransaction, this endpoint enables clients to drain recoverable balances from origin or destination intent addresses after an intent has failed, expired, or otherwise left funds behind.

​
Use Cases

  • Recover an intent’s origin deposit when the route became unfillable
  • Sweep dust or leftover balances from an intent wallet
  • Refund a user from a stranded intent address

​
Request Parameters

​
Required Fields

  • intentId (string): The unique ID of the intent to recover.

​
Optional Fields

  • intentAddress (string): If omitted, the backend auto-selects the origin or destination intent address by recoverable balance.
  • refundToAddress (string): Defaults to the intent owner address when omitted.
  • tokenAddress (string): Constrain recovery token selection when multiple recoverable tokens exist.

​
Response

  • intentId (string)
  • intentProtocol (IntentProtocolVersion)
  • intentAddress (string): The intent wallet being recovered.
  • chainId (number): Chain ID of the intent wallet.
  • intentSource (string): "origin" or "destination" — which intent wallet was selected for recovery.
  • recoveryTokens (array of IntentTokenBalance, optional): The token balances eligible for recovery.
  • payload (any): Payload to be signed.
  • typedData (any): EIP-712 typed data for client signing.
  • payloadHash (string)

​
Flow

  1. Call PrepareIntentRecovery to get the payload and typed data.
  2. Have the user sign the typed data with their wallet.
  3. Call BuildIntentRecoveryTransaction with the signed payload to receive the executable transaction.
  4. Broadcast the transaction.

​
Example

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/PrepareIntentRecovery', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_ACCESS_KEY'
  },
  body: JSON.stringify({ intentId: 'intent_abc123' })
});

const { typedData, payload, payloadHash, intentAddress } = await response.json();

// Sign typedData with the user's wallet, then continue with BuildIntentRecoveryTransaction
const signature = await walletClient.signTypedData(typedData);

​
Next Steps

BuildIntentRecoveryTransaction

Build the executable recovery transaction

AbortIntent

Notify Trails of an on-chain abort

Body

application/json
​
intentId
string
required
​
intentAddress
string
​
refundToAddress
string
​
tokenAddress
string

Response

OK

​
intentId
string
required
​
intentProtocol
enum<string>
required

Represented as string on the server side

Available options:
v1,
v1_5
​
intentAddress
string
required
​
chainId
number
required
​
intentSource
string
required
​
payload
object
required
​
typedData
object
required
​
payloadHash
string
required
​
recoveryTokens
object[]

[]IntentTokenBalance