GetIntent

POST /rpc/Trails/GetIntent

cURL

cURL

curl --request POST \
  --url https://api.example.com/rpc/Trails/GetIntent \
  --header 'Content-Type: application/json' \
  --data '
{
  "intentId": "<string>"
}
'

200

{
  "intent": {
    "id": 123,
    "projectId": 123,
    "intentId": "<string>",
    "status": "QUOTED",
    "quoteRequest": {
      "ownerAddress": "<string>",
      "originChainId": 123,
      "originTokenAddress": "<string>",
      "destinationChainId": 123,
      "destinationTokenAddress": "<string>",
      "destinationToAddress": "<string>",
      "destinationApproveAddress": "<string>",
      "destinationCallData": "<string>",
      "destinationCallValue": 123,
      "originTokenAmount": 123,
      "destinationTokenAmount": 123,
      "tradeType": "EXACT_INPUT",
      "fundMethod": "WALLET",
      "onlyNativeGasFee": true,
      "options": {
        "intentProtocol": "v1",
        "swapProvider": "AUTO",
        "bridgeProvider": "AUTO",
        "swapProviderFallback": true,
        "bridgeProviderFallback": true,
        "preference": "RECOMMENDED",
        "slippageTolerance": 123,
        "trailsAddressOverrides": {
          "sequenceWalletFactoryAddress": "<string>",
          "sequenceWalletMainModuleAddress": "<string>",
          "sequenceWalletMainModuleUpgradableAddress": "<string>",
          "sequenceWalletGuestModuleAddress": "<string>",
          "sequenceWalletUtilsAddress": "<string>"
        }
      }
    },
    "ownerAddress": "<string>",
    "originChainId": 123,
    "destinationChainId": 123,
    "originTokenAddress": "<string>",
    "destinationTokenAddress": "<string>",
    "originIntentAddress": "<string>",
    "salt": 123,
    "depositTransaction": {
      "toAddress": "<string>",
      "tokenAddress": "<string>",
      "amount": 123,
      "chainId": 123,
      "to": "<string>",
      "data": "<string>",
      "value": 123,
      "decimals": 123
    },
    "originCalls": {
      "chainId": 123,
      "calls": [
        {
          "to": "<string>",
          "value": 123,
          "data": "<string>",
          "gasLimit": 123,
          "delegateCall": true,
          "onlyFallback": true,
          "behaviorOnError": 123
        }
      ],
      "space": 123,
      "nonce": 123
    },
    "originPrecondition": {
      "type": "<string>",
      "chainId": 123,
      "ownerAddress": "<string>",
      "tokenAddress": "<string>",
      "minAmount": 123
    },
    "originMetaTxn": {
      "id": "<string>",
      "chainId": 123,
      "walletAddress": "<string>",
      "contract": "<string>",
      "input": "<string>",
      "bridgeGas": 123
    },
    "quote": {
      "routeProviders": [
        "AUTO"
      ],
      "routeProvidersRequestIds": [
        "<string>"
      ],
      "routeProvidersFeeUsd": [
        123
      ],
      "fromAmount": 123,
      "fromAmountMin": 123,
      "fromAmountUsd": 123,
      "fromAmountMinUsd": 123,
      "toAmount": 123,
      "toAmountMin": 123,
      "toAmountUsd": 123,
      "toAmountMinUsd": 123,
      "maxSlippage": 123,
      "priceImpact": 123,
      "priceImpactUsd": 123,
      "priceImpactDetails": {
        "executionPriceImpact": {
          "priceImpact": 123,
          "priceImpactUsd": 123
        },
        "marketPriceImpact": {
          "priceImpact": 123,
          "priceImpactUsd": 123
        },
        "providerFeesPriceImpact": {
          "priceImpact": 123,
          "priceImpactUsd": 123
        },
        "trailsFeesPriceImpact": {
          "priceImpact": 123,
          "priceImpactUsd": 123
        },
        "netPriceImpact": {
          "priceImpact": 123,
          "priceImpactUsd": 123
        }
      },
      "estimatedDuration": 123
    },
    "fees": {
      "originGas": {
        "chainId": 123,
        "totalGasLimit": 123,
        "gasPrice": 123,
        "nativeTokenSymbol": "<string>",
        "chainGasUsageStatus": "NORMAL",
        "totalFeeAmount": 123,
        "totalFeeUsd": "<string>",
        "metaTxnFeeDetails": {
          "metaTxnId": "<string>",
          "estimatedGasLimit": 123,
          "feeNative": 123
        },
        "metaTxnGasQuote": "<string>",
        "nativeTokenPriceUsd": 123
      },
      "provider": {
        "quoteProvider": "<string>",
        "quoteProviderFee": 123,
        "quoteProviderFeeUsd": 123,
        "trailsFee": 123,
        "trailsFeeUsd": 123,
        "quoteProviderWithTrailsFee": 123,
        "providerWithTrailsFeeUsd": 123,
        "totalFeeAmount": 123,
        "totalFeeUsd": 123
      },
      "feeTokenAddress": "<string>",
      "feeTokenAmount": 123,
      "feeTokenUsd": 123,
      "feeTokenTotal": 123,
      "gasFeeTotal": 123,
      "gasFeeUsd": 123,
      "trailsFeeTotal": 123,
      "trailsFeeUsd": 123,
      "collectorFeeTotal": 123,
      "collectorFeeUsd": 123,
      "providerFeeTotal": 123,
      "providerFeeUsd": 123,
      "totalFeeAmount": 123,
      "totalFeeUsd": 123,
      "destinationGas": {
        "chainId": 123,
        "totalGasLimit": 123,
        "gasPrice": 123,
        "nativeTokenSymbol": "<string>",
        "chainGasUsageStatus": "NORMAL",
        "totalFeeAmount": 123,
        "totalFeeUsd": "<string>",
        "metaTxnFeeDetails": {
          "metaTxnId": "<string>",
          "estimatedGasLimit": 123,
          "feeNative": 123
        },
        "metaTxnGasQuote": "<string>",
        "nativeTokenPriceUsd": 123
      }
    },
    "trailsVersion": "<string>",
    "trailsContracts": {
      "trailsIntentEntrypointAddress": "<string>",
      "trailsRouterAddress": "<string>",
      "trailsRouterShimAddress": "<string>",
      "trailsUtilsAddress": "<string>"
    },
    "expiresAt": "<string>",
    "destinationIntentAddress": "<string>",
    "passthrough": true,
    "destinationCalls": {
      "chainId": 123,
      "calls": [
        {
          "to": "<string>",
          "value": 123,
          "data": "<string>",
          "gasLimit": 123,
          "delegateCall": true,
          "onlyFallback": true,
          "behaviorOnError": 123
        }
      ],
      "space": 123,
      "nonce": 123
    },
    "destinationPrecondition": {
      "type": "<string>",
      "chainId": 123,
      "ownerAddress": "<string>",
      "tokenAddress": "<string>",
      "minAmount": 123
    },
    "destinationMetaTxn": {
      "id": "<string>",
      "chainId": 123,
      "walletAddress": "<string>",
      "contract": "<string>",
      "input": "<string>",
      "bridgeGas": 123
    },
    "intentProtocol": "v1",
    "updatedAt": "<string>",
    "createdAt": "<string>"
  }
}

Overview

The GetIntent endpoint retrieves the complete intent object for a specific intent ID. This provides all the details about the intent including quote information, fee breakdown, transaction calls, and metadata.

Use Cases

• Retrieve full intent details after creation
• Review quote and fee information
• Inspect transaction calls and preconditions
• Verify intent parameters
• Debug issues with intent execution
• Display intent details in UI

Request Parameters

Required Fields

• intentId (string): The unique identifier of the intent

Response

The response includes:

• intent (Intent): Complete intent object with all details

Intent Object Structure

The intent object contains comprehensive information:

Core Fields

• id (number): Internal database ID
• intentId (string): Unique intent identifier
• status (IntentStatus): Current status
• ownerAddress (string): Wallet address of the intent owner
• originIntentAddress (string): Intent contract address on origin chain
• destinationIntentAddress (string): Intent contract address on destination chain
• destinationSalt (number): Salt for deterministic intent address generation
• trailsVersion (string): Version of Trails protocol used
• expiresAt (string): Intent expiration timestamp
• createdAt (string): Creation timestamp
• updatedAt (string): Last update timestamp

Quote Request

• quoteRequest (QuoteIntentRequest): Original quote parameters
  • Origin and destination chain/token details
  • Amounts and trade type
  • Options (provider, slippage, etc.)

Transaction Details

• depositTransaction (DepositTransaction): Deposit details

  • Token address and amount
  • Recipient address
  • Token decimals

• calls (IntentCalls[]): Cross-chain calls to execute

  • Chain ID for each call set
  • Transaction calls with calldata
  • Nonce and space information

• preconditions (TransactionPrecondition[]): Pre-execution checks

  • Token balance requirements
  • Minimum amount validations

• metaTxns (MetaTxn[]): Meta-transaction information

  • Meta-transaction IDs
  • Wallet addresses
  • Contract targets

Quote Information

• quote (IntentProviderQuote): Quote provider details
  • Provider name and request ID
  • Input/output amounts and minimums
  • Slippage and price impact
  • Provider fees in USD

Fee Breakdown

• fees (IntentFees): Comprehensive fee information
  • originGas: Origin chain gas fees
  • destinationGas: Destination chain gas fees
  • provider: Provider fees (quote provider + Trails)
  • feeTokenAddress: Token used for fees
  • feeTokenTotal: Total fee in fee token
  • totalFeeAmount: Total fee amount
  • totalFeeUsd: Total fee in USD

Example

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

const { intent } = await intentResponse.json();

console.log('Intent ID:', intent.intentId);
console.log('Status:', intent.status);
console.log('Owner:', intent.ownerAddress);
console.log('Expires:', intent.expiresAt);

// Quote information
console.log('From Amount:', intent.quote.fromAmount);
console.log('To Amount:', intent.quote.toAmount);
console.log('Price Impact:', intent.quote.priceImpact);

// Fee breakdown
console.log('Total Fee (USD):', intent.fees.totalFeeUsd);
console.log('Origin Gas Fee:', intent.fees.originGas.totalFeeUsd);
console.log('Destination Gas Fee:', intent.fees.destinationGas?.totalFeeUsd);
console.log('Provider Fee:', intent.fees.provider.totalFeeUsd);

Detailed Fee Inspection

function analyzeFees(intent: Intent) {
  const fees = intent.fees;
  
  console.log('=== Fee Breakdown ===');
  
  // Gas fees
  console.log('\nOrigin Chain Gas:');
  console.log('  Chain ID:', fees.originGas.chainId);
  console.log('  Gas Limit:', fees.originGas.totalGasLimit);
  console.log('  Gas Price:', fees.originGas.gasPrice);
  console.log('  Native Token:', fees.originGas.nativeTokenSymbol);
  console.log('  Cost (USD):', fees.originGas.totalFeeUsd);
  console.log('  Network Status:', fees.originGas.chainGasUsageStatus);
  
  console.log('\nDestination Chain Gas:');
  console.log('  Chain ID:', fees.destinationGas?.chainId);
  console.log('  Gas Limit:', fees.destinationGas?.totalGasLimit);
  console.log('  Gas Price:', fees.destinationGas?.gasPrice);
  console.log('  Native Token:', fees.destinationGas?.nativeTokenSymbol);
  console.log('  Cost (USD):', fees.destinationGas?.totalFeeUsd);
  console.log('  Network Status:', fees.destinationGas?.chainGasUsageStatus);
  
  // Provider fees
  console.log('\nProvider Fees:');
  console.log('  Quote Provider:', fees.provider.quoteProvider);
  console.log('  Provider Fee:', fees.provider.quoteProviderFeeUsd, 'USD');
  console.log('  Trails Fee:', fees.provider.trailsFeeUsd, 'USD');
  console.log('  Total Provider:', fees.provider.totalFeeUsd, 'USD');
  
  // Grand total
  console.log('\n=== TOTAL ===');
  console.log('Fee Token:', fees.feeTokenAddress);
  console.log('Total Amount:', fees.totalFeeAmount);
  console.log('Total USD:', fees.totalFeeUsd);
}

const { intent } = await getIntent('intent_123abc');
analyzeFees(intent);

Inspecting Transaction Calls

function inspectCalls(intent: Intent) {
    console.log('=== Transaction Origin Calls ===\n');

    console.log('Origin Chain ID:', intent.originCalls.chainId);
    console.log('Origin Space:', intent.originCalls.space);
    console.log('Origin Nonce:', intent.originCalls.nonce);
    console.log('Origin Calls:', intent.originCalls.calls.length);

    intent.originCalls.calls.forEach((call, callIndex) => {
        console.log(`\n  Call ${callIndex + 1}:`);
        console.log('    To:', call.to);
        console.log('    Value:', call.value);
        console.log('    Data:', call.data);
        console.log('    Gas Limit:', call.gasLimit);
        console.log('    Delegate:', call.delegateCall);
    });

    console.log('=== Transaction Destination Calls ===\n');

    console.log('Destination Chain ID:', intent.destinationCalls?.chainId);
    console.log('Destination Space:', intent.destinationCalls?.space);
    console.log('Destination Nonce:', intent.destinationCalls?.nonce);
    console.log('Destination Calls:', intent.destinationCalls?.calls.length);

    intent.destinationCalls?.calls.forEach((call, callIndex) => {
        console.log(`\n  Call ${callIndex + 1}:`);
        console.log('    To:', call.to);
        console.log('    Value:', call.value);
        console.log('    Data:', call.data);
        console.log('    Gas Limit:', call.gasLimit);
        console.log('    Delegate:', call.delegateCall);
    });
}

const { intent } = await getIntent('intent_123abc');
inspectCalls(intent);

Use Cases

1. Display Intent Summary in UI

import { TrailsApi, type Intent } from "@0xtrails/api";
import { useEffect, useState } from "react";

const trailsApi = new TrailsApi('YOUR_API_KEY')

export const IntentSummary = ({ intentId }: { intentId: string }) => {
    const [intent, setIntent] = useState<Intent | null>(null);

    useEffect(() => {
        trailsApi.getIntent({ intentId }).then(({ intent }) => setIntent(intent));
    }, [intentId]);

    if (!intent) return <div>Loading...</div>;

    return (
        <div>
            <h2>Intent {intent.intentId}</h2>
            <div>Status: {intent.status}</div>
            <div>From: Chain {intent.quoteRequest.originChainId}</div>
            <div>To: Chain {intent.quoteRequest.destinationChainId}</div>
            <div>Amount: {intent.quote.fromAmount} → {intent.quote.toAmount}</div>
            <div>Total Fee: ${intent.fees.totalFeeUsd}</div>
            <div>Expires: {new Date(intent.expiresAt).toLocaleString()}</div>
        </div>
    );
}

2. Verify Intent Before Signing

import { TrailsApi } from "@0xtrails/api";

const trailsApi = new TrailsApi('YOUR_API_KEY')

export async function verifyBeforeSigning(intentId: string) {
    const { intent } = await trailsApi.getIntent({ intentId });

    // Check expiration
    const expiresAt = new Date(intent.expiresAt);
    const now = new Date();

    if (expiresAt < now) {
        throw new Error('Intent has expired');
    }

    // Check fees are reasonable
    if (intent.fees.totalFeeUsd > 10) {
        console.warn('High fees detected:', intent.fees.totalFeeUsd);
    }

    const slippage = (intent.quote.fromAmount - intent.quote.fromAmountMin) / intent.quote.fromAmount;
    // Check if slippage is greater than 5%
    if (slippage > 0.05) {
        console.warn('High slippage:', slippage * BigInt(100), '%');
    }

    return intent;
}

Use this endpoint to retrieve intent details at any time. The intent object remains accessible even after execution completes.

Next Steps

• Use GetIntentReceipt to check execution status and get transaction hashes
• Use SearchIntents to find all intents for a specific address
• Modify and recommit expired intents with fresh quotes

Body

application/json

intentId · string · required

Response

200

application/json

OK

intent · object · required

Show child attributes