# CCIP Tools Documentation

> Auto-generated context file for LLMs. Generated: 2026-04-22
> For CCIP protocol details (glossary, message lifecycle, architecture): https://docs.chain.link/ccip/llms-full.txt

## Overview

CCIP Tools is a TypeScript toolkit for Chainlink CCIP (Cross-Chain Interoperability Protocol).

- **SDK Package:** `@chainlink/ccip-sdk`
- **CLI Package:** `@chainlink/ccip-cli`
- **REST API:** https://api.ccip.chain.link

---

## CCIP Protocol Reference

For detailed information about CCIP concepts, refer to the official documentation:

- **Glossary** (chainSelector, OnRamp, OffRamp, Lane, DON): https://docs.chain.link/ccip/llms-full.txt
- **Message Lifecycle** (Sent → Committed → Blessed → Success/Failed): https://docs.chain.link/ccip/llms-full.txt
- **Architecture**: https://docs.chain.link/ccip/llms-full.txt

---

## Tools Architecture (SDK, CLI, API)

The following Mermaid diagram shows the dependencies between SDK, CLI, and CCIP API:

```mermaid
flowchart TD
    subgraph NPM["<b>CCIP TypeScript Packages</b>"]
        SDK["<b>@chainlink/ccip-sdk</b><br/><i>Multi-chain SDK<br/>(EVM, Solana, Aptos, Sui, TON)</i>"]
        CLI["<b>@chainlink/ccip-cli</b><br/><i>Command-line tool</i>"]
        MCP["<b>MCP Server</b><br/><i>Tools, Resources, Prompts</i>"]
    end

    subgraph INFRA["<b>CCIP Infrastructure</b>"]
        CONTRACTS["<b>Onchain Contracts/Programs</b><br/><i>Read: Lane configs, pool configs, fee quotes, message events<br/>Write: ccipSend, execute (manual)</i>"]
        API["<b>CCIP API</b><br/><i>Message queries, lane latency</i>"]
    end

    subgraph EXTERNAL_API["<b>External Attestation APIs</b>"]
        CIRCLE["<b>Circle API</b><br/><i>USDC/CCTP attestations</i>"]
        LOMBARD["<b>Lombard API</b><br/><i>LBTC attestations</i>"]
    end

    subgraph APPS["<b>Applications & Integrations</b>"]
        INTERNAL["<b>Internal dApps</b>"]
        DAPPS["<b>External Cross-chain dApps</b>"]
        OPS["<b>Ops</b><br/><i>Message debugging, sending messages,<br/>manual execution</i>"]
    end

    subgraph AI["<b>AI Applications & Agents</b>"]
        CLAUDE_APPS["<b>Claude Apps</b><br/><i>Claude Desktop, Claude Code</i>"]
        IDE["<b>AI-Powered IDEs</b><br/><i>Cursor, VS Code</i>"]
        AGENTS["<b>Agent Frameworks</b><br/><i>OpenAI Agents SDK, LangChain,<br/>CrewAI, AutoGPT</i>"]
    end

    %% CLI and MCP depend on SDK
    CLI -->|"uses"| SDK
    MCP -->|"uses"| SDK

    %% SDK interacts with infrastructure
    SDK -->|"read/write<br/>transactions"| CONTRACTS
    SDK -->|"read<br/>status, latency"| API
    SDK -->|"read<br/>attestations"| CIRCLE
    SDK -->|"read<br/>attestations"| LOMBARD

    %% Applications use packages
    INTERNAL -->|"npm install"| SDK
    DAPPS -->|"npm install"| SDK
    OPS -->|"npm install"| SDK
    OPS -->|"npx / npm global install"| CLI

    %% AI Applications use MCP Server
    CLAUDE_APPS -->|"MCP protocol"| MCP
    IDE -->|"MCP protocol"| MCP
    AGENTS -->|"MCP protocol"| MCP

    %% Styling
    classDef npmStyle fill:#E3ECFF,stroke:#0847F7,stroke-width:2px,color:#0B101C
    classDef sdkStyle fill:#8AA6F9,stroke:#0847F7,stroke-width:2px,color:#0B101C
    classDef cliStyle fill:#8AA6F9,stroke:#0847F7,stroke-width:2px,color:#0B101C
    classDef mcpStyle fill:#C5B4E3,stroke:#7C3AED,stroke-width:2px,color:#0B101C
    classDef infraStyle fill:#F8FAFF,stroke:#0847F7,stroke-width:2px,color:#0B101C
    classDef externalStyle fill:#FFF5E6,stroke:#E67E22,stroke-width:2px,color:#0B101C
    classDef appStyle fill:#F2EBE0,stroke:#217B71,stroke-width:2px,color:#0B101C
    classDef aiStyle fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#0B101C

    class NPM npmStyle
    class SDK,CLI sdkStyle
    class MCP mcpStyle
    class INFRA,CONTRACTS,API infraStyle
    class EXTERNAL_API,CIRCLE,LOMBARD externalStyle
    class APPS,INTERNAL,DAPPS,OPS appStyle
    class AI,CLAUDE_APPS,IDE,AGENTS aiStyle
```


---

## SDK Exports (@chainlink/ccip-sdk)

### Classes (126)

- `AptosChain`
- `EVMChain`
- `SolanaChain`
- `SuiChain`
- `TONChain`
- `CCIPError`
- `isTransientError`
- `CCIPChainFamilyMismatchError`
- `CCIPChainFamilyUnsupportedError`
- `CCIPChainNotFoundError`
- `CCIPMethodUnsupportedError`
- `CCIPNetworkFamilyUnsupportedError`
- `CCIPBlockNotFoundError`
- `CCIPTransactionNotFoundError`
- `CCIPLogsAddressRequiredError`
- `CCIPLogsWatchRequiresFinalityError`
- `CCIPLogsWatchRequiresStartError`
- `CCIPMessageBatchIncompleteError`
- `CCIPMessageIdNotFoundError`
- `CCIPMessageIdValidationError`
- `CCIPMessageInvalidError`
- `CCIPMessageNotFoundInTxError`
- `CCIPMessageNotInBatchError`
- `CCIPMessageNotVerifiedYetError`
- `CCIPMessageRetrievalError`
- `CCIPLaneNotFoundError`
- `CCIPOffRampNotFoundError`
- `CCIPOnRampRequiredError`
- `CCIPCommitNotFoundError`
- `CCIPMerkleFlagsMismatchError`
- `CCIPMerkleHashesTooLargeError`
- `CCIPMerkleInternalError`
- `CCIPMerkleProofEmptyError`
- `CCIPMerkleProofFlagsMismatchError`
- `CCIPMerkleProofIncompleteError`
- `CCIPMerkleProofTooLargeError`
- `CCIPMerkleRootMismatchError`
- `CCIPMerkleTreeEmptyError`
- `CCIPHasherVersionUnsupportedError`
- `CCIPVersionFeatureUnavailableError`
- `CCIPVersionRequiresLaneError`
- `CCIPVersionUnsupportedError`
- `CCIPExtraArgsInvalidError`
- `CCIPExtraArgsParseError`
- `CCIPLegacyTokenPoolsUnsupportedError`
- `CCIPTokenDecimalsInsufficientError`
- `CCIPTokenNotConfiguredError`
- `CCIPTokenNotFoundError`
- `CCIPTokenNotInRegistryError`
- `CCIPContractNotRouterError`
- `CCIPContractTypeInvalidError`
- `CCIPWalletInvalidError`
- `CCIPWalletNotSignerError`
- `CCIPExecTxNotConfirmedError`
- `CCIPExecTxRevertedError`
- `CCIPReceiptNotFoundError`
- `CCIPLbtcAttestationError`
- `CCIPLbtcAttestationNotApprovedError`
- `CCIPLbtcAttestationNotFoundError`
- `CCIPUsdcAttestationError`
- `CCIPUsdcBurnFeesError`
- `CCIPBlockTimeNotFoundError`
- `CCIPCctpDecodeError`
- `CCIPExecutionReportChainMismatchError`
- `CCIPExecutionStateInvalidError`
- `CCIPExtraArgsLengthInvalidError`
- `CCIPLogDataMissingError`
- `CCIPSolanaComputeUnitsExceededError`
- `CCIPSolanaExtraArgsEncodingError`
- `CCIPSolanaFeeResultInvalidError`
- `CCIPSolanaLaneVersionUnsupportedError`
- `CCIPSolanaLookupTableNotFoundError`
- `CCIPSolanaOffRampEventsNotFoundError`
- `CCIPSolanaRefAddressesNotFoundError`
- `CCIPSolanaRouterConfigNotFoundError`
- `CCIPSplTokenInvalidError`
- `CCIPTokenAccountNotFoundError`
- `CCIPTokenAmountInvalidError`
- `CCIPTokenDataParseError`
- `CCIPTokenMintInvalidError`
- `CCIPTokenMintNotFoundError`
- `CCIPTokenPoolChainConfigNotFoundError`
- `CCIPTokenPoolInfoNotFoundError`
- `CCIPTokenPoolStateNotFoundError`
- `CCIPTopicsInvalidError`
- `CCIPTransactionNotFinalizedError`
- `CCIPAptosAddressModuleRequiredError`
- `CCIPAptosExtraArgsEncodingError`
- `CCIPAptosExtraArgsV2RequiredError`
- `CCIPAptosHasherVersionUnsupportedError`
- `CCIPAptosLogInvalidError`
- `CCIPAptosNetworkUnknownError`
- `CCIPAptosRegistryTypeInvalidError`
- `CCIPAptosTokenNotRegisteredError`
- `CCIPAptosTopicInvalidError`
- `CCIPAptosTransactionInvalidError`
- `CCIPAptosTransactionTypeInvalidError`
- `CCIPAptosTransactionTypeUnexpectedError`
- `CCIPAptosWalletInvalidError`
- `CCIPSuiHasherVersionUnsupportedError`
- `CCIPSuiLogInvalidError`
- `CCIPSuiMessageVersionInvalidError`
- `CCIPBorshMethodUnknownError`
- `CCIPBorshTypeUnknownError`
- `CCIPAbortError`
- `CCIPBlockBeforeTimestampNotFoundError`
- `CCIPDataFormatUnsupportedError`
- `CCIPDataParseError`
- `CCIPHttpError`
- `CCIPLogDataInvalidError`
- `CCIPLogTopicsNotFoundError`
- `CCIPLogsNotFoundError`
- `CCIPMessageDecodeError`
- `CCIPNotImplementedError`
- `CCIPRpcNotFoundError`
- `CCIPTimeoutError`
- `CCIPTypeVersionInvalidError`
- `CCIPApiClientNotAvailableError`
- `CCIPUnexpectedPaginationError`
- `CCIPViemAdapterError`
- `CCIPAddressInvalidError`
- `CCIPSourceChainUnsupportedError`
- `CCIPArgumentInvalidError`
- `CCIPInsufficientBalanceError`
- `CCIPInteractiveRequiredError`
- `isServerError`

### Functions (19)

- `calculateManualExecProof()`
- `discoverOffRamp()`
- `decodeExtraArgs()`
- `encodeExtraArgs()`
- `estimateReceiveExecution()`
- `getOffchainTokenData()`
- `decodeMessage()`
- `sourceToDestTokenAddresses()`
- `bigIntReplacer()`
- `bigIntReviver()`
- `bytesToBuffer()`
- `decodeAddress()`
- `getDataBytes()`
- `isSupportedTxHash()`
- `networkInfo()`
- `withRetry()`
- `getCCIPExplorerLinks()`
- `getCCIPExplorerUrl()`
- `supportedChains()`

### Types (44)

- `CCIPAPIClient`
- `DEFAULT_API_BASE_URL`
- `SDK_VERSION`
- `SDK_VERSION_HEADER`
- `DEFAULT_API_RETRY_CONFIG`
- `LaneFeature`
- `CCTP_FINALITY_FAST`
- `CCTP_FINALITY_STANDARD`
- `CCIPVersion`
- `ExecutionState`
- `IntentStatus`
- `MessageStatus`
- `CCIP_EXPLORER_BASE_URL`
- `APICCIPRequestMetadata`
- `APIErrorResponse`
- `CCIPAPIClientContext`
- `LaneLatencyResponse`
- `MessageSearchFilters`
- `MessageSearchPage`
- `MessageSearchResult`
- `ApiRetryConfig`
- `Chain`
- `ChainContext`
- `ChainGetter`
- `ChainStatic`
- `GetBalanceOpts`
- `LaneFeatures`
- `LogFilter`
- `RateLimiterState`
- `RegistryTokenConfig`
- `TokenInfo`
- `TokenPoolConfig`
- `TokenPoolRemote`
- `TokenPrice`
- `TokenTransferFee`
- `TokenTransferFeeConfig`
- `TokenTransferFeeOpts`
- `TotalFeesEstimate`
- `WithRetryConfig`
- `UnsignedAptosTx`
- `UnsignedEVMTx`
- `UnsignedSolanaTx`
- `UnsignedSuiTx`
- `UnsignedTONTx`

### Enums (2)

- `ChainFamily`
- `NetworkType`

---

## Chain Methods (Full Signatures)

Methods available on chain instances (EVMChain, SolanaChain, AptosChain, SuiChain, TONChain):

### `[abstract] getBlockTimestamp(block: number | 'finalized'): Promise<number>`

### `[abstract] getTransaction(hash: string): Promise<ChainTransaction>`

### `async waitFinalized({
    request: { log, tx },
    finality = 'finalized',
    cancel$,
  }: {
    request: SetOptional<
      PickDeep<
        CCIPRequest,
        | `log.${'address' | 'blockNumber' | 'transactionHash' | 'topics' | 'tx.timestamp'}`
        | 'tx.timestamp'
      >,
      'tx'
    >
    finality?: number | 'finalized'
    cancel$?: Promise<unknown>
  }): Promise<true>`

### `[abstract] getLogs(opts: LogFilter): AsyncIterableIterator<ChainLog>`

### `async getMessagesInTx(tx: string | ChainTransaction): Promise<CCIPRequest[]>`

### `async getMessageById(messageId: string,
    _opts?: { page?: number; onRamp?: string },): Promise<CCIPRequest>`

### `async getExecutionInput({
    request,
    verifications,
    ...opts
  }: {
    request: CCIPRequest
    verifications: CCIPVerifications
  } & Pick<LogFilter, 'page'>): Promise<ExecutionInput>`

### `[abstract] typeAndVersion(address: string,): Promise<[type: string, version: string, typeAndVersion: string, suffix?: string]>`

### `[abstract] getRouterForOnRamp(onRamp: string, destChainSelector: bigint): Promise<string>`

### `[abstract] getRouterForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string>`

### `[abstract] getNativeTokenForRouter(router: string): Promise<string>`

### `[abstract] getOffRampsForRouter(router: string, sourceChainSelector: bigint): Promise<string[]>`

### `[abstract] getOnRampForRouter(router: string, destChainSelector: bigint): Promise<string>`

### `[abstract] getOnRampsForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string[]>`

### `[abstract] getTokenForTokenPool(tokenPool: string): Promise<string>`

### `[abstract] getTokenInfo(token: string): Promise<TokenInfo>`

### `[abstract] getBalance(opts: GetBalanceOpts): Promise<bigint>`

### `[abstract] getTokenAdminRegistryFor(address: string): Promise<string>`

### `[abstract] getFee(opts: Omit<SendMessageOpts, 'approveMax'>): Promise<bigint>`

### `[abstract] generateUnsignedSendMessage(opts: SendMessageOpts & {
      /** Sender address (address of wallet which will send the message): void`

### `[abstract] sendMessage(opts: SendMessageOpts & {
      /** Signer instance (chain-dependent): void`

### `async getOffchainTokenData(request: PickDeep<CCIPRequest, 'tx.hash' | `message`>,): Promise<OffchainTokenData[]>`

### `[abstract] generateUnsignedExecute(opts: ExecuteOpts & {
      /** address which will be used to send the report tx */
      payer: string
    },): Promise<UnsignedTx[F]>`

### `[abstract] execute(opts: ExecuteOpts & {
      // Signer instance (chain-dependent): void`

### `async getVerifications({
    offRamp,
    request,
    ...hints
  }: {
    /** address of offRamp or commitStore contract */
    offRamp: string
    /** CCIPRequest subset object */
    request: PickDeep<
      CCIPRequest,
      'lane' | `message.${'sequenceNumber' | 'messageId'}` | 'tx.timestamp'
    >
  } & Pick<LogFilter, 'page' | 'watch' | 'startBlock'>): Promise<CCIPVerifications>`

### `async getLaneLatency(destChainSelector: bigint,
    numberOfBlocks?: number,): Promise<LaneLatencyResponse>`

### `getLaneFeatures(_opts: {
    router: string
    destChainSelector: bigint
    token?: string
  }): Promise<Partial<LaneFeatures>>`

### `async getExecutionReceiptInTx(tx: string | ChainTransaction): Promise<CCIPExecution>`

### `[abstract] getSupportedTokens(address: string, opts?: { page?: number }): Promise<string[]>`

### `[abstract] getRegistryTokenConfig(registry: string, token: string): Promise<RegistryTokenConfig>`

### `[abstract] getTokenPoolConfig(tokenPool: string,
    feeOpts?: TokenTransferFeeOpts,): Promise<TokenPoolConfig>`

### `[abstract] getTokenPoolRemotes(tokenPool: string,
    remoteChainSelector?: bigint,): Promise<Record<string, TokenPoolRemote>>`

### `async getTokenPoolRemote(tokenPool: string,
    remoteChainSelector: bigint,): Promise<TokenPoolRemote>`

### `[abstract] getFeeTokens(router: string): Promise<Record<string, TokenInfo>>`

### `assertNoUnknownFields(message.extraArgs, V3_FIELDS, 'GenericExtraArgsV3'): void`

### `getTotalFeesEstimate(_opts: Omit<SendMessageOpts, 'approveMax'>): Promise<TotalFeesEstimate>`

### `getTokenPrice(_opts: { router: string; token: string; timestamp?: number }): Promise<TokenPrice>`

### `fromUrl(url: string, ctx?: ChainContext): Promise<Chain<F>>`

### `decodeMessage(log: Pick<ChainLog, 'data'>): CCIPMessage | undefined`

### `decodeExtraArgs(extraArgs: BytesLike,): | (EVMExtraArgsV1 &`

### `encodeExtraArgs(extraArgs: ExtraArgs): string`

### `decodeCommits(log: Pick<ChainLog, 'data'>, lane?: Lane): CommitReport[] | undefined`

### `decodeReceipt(log: Pick<ChainLog, 'data'>): ExecutionReceipt | undefined`

### `getAddress(bytes: BytesLike): string`

### `isTxHash(v: unknown): v is string`

### `getDestLeafHasher(lane: Lane, ctx?: WithLogger): LeafHasher`

### `buildMessageForDest(message: MessageInput): AnyMessage`

---

## CLI Commands (8)

### `laneLatency <source> <dest>` (aliases: latency)

Query real-time lane latency between source and destination chains

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--block-confirmations` | `-c` | No | Number of block confirmations to use for latency calculation |

### `manualExec <tx-hash-or-id>` (aliases: manual-exec)

Execute manually pending or failed messages

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--log-index` | - | No | Log index of message to execute (if more than one in request tx) |
| `--gas-limit` | `-L, compute-units` | No | Override gas limit or compute units for receivers callback (0 keeps original) |
| `--tokens-gas-limit` | - | No | Override gas limit for tokens releaseOrMint calls (0 keeps original, v1.5..v1.6 only) |
| `--estimate-gas-limit` | - | No | Estimate gas limit for receivers callback; argument is a % margin to add to the estimate |
| `--wallet` | `-w` | No | Wallet to send transactions with; pass `ledger[:index_or_derivation]` for Ledger, `foundry:<name>` or `hardhat:<name>` for named keystores, or private key in `USER_KEY` environment variable |
| `--force-buffer` | - | No | Forces the usage of buffering for Solana execution. |
| `--force-lookup-table` | - | No | Forces the creation & usage of an ad-hoc lookup table for Solana execution. |
| `--clear-leftover-accounts` | - | No | Clears buffers (if a previous attempt was aborted) or any ALT owned by this sender. |
| `--receiver-object-ids` | - | No | Receiver object IDs for Sui execution (if executing on Sui destination) |

### `parse <data>` (aliases: parseBytes, parse-bytes, parseData, parse-data, )

Try to parse and print errors, revert reasons or function call or event data

### `search`

Search CCIP entities via API

### `send`

Send a CCIP message from source to destination chain

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--source` | `-s` | Yes | Source chain: chainId, selector, or name |
| `--dest` | `-d` | Yes | Destination chain: chainId, selector, or name |
| `--router` | `-r` | Yes | Router contract address on source |
| `--receiver` | `-to` | No | Receiver address on destination; defaults to sender if same chain family |
| `--data` | - | No | Data payload to send (0x-bytearrays are used as is;  |
| `--gas-limit` | `-L, compute-units` | No | Gas limit for receiver callback; defaults to ramp config |
| `--estimate-gas-limit` | - | No | Estimate gas limit with % margin (e.g., 10 for +10%) |
| `--allow-out-of-order-exec` | `-ooo` | No | Allow out-of-order execution (v1.5+ lanes) |
| `--fee-token` | - | No | Fee token address or symbol (default: native) |
| `--transfer-tokens` | `-t` | No | Token amounts to transfer: token=amount |
| `--wallet` | `-w` | No | Wallet: ledger[:index], foundry:<name>, hardhat:<name>, or private key |
| `--token-receiver` | - | No | Solana token receiver (if different from program receiver) |
| `--account` | `-receiver-object-id` | No | Solana accounts (append =rw for writable) or Sui object IDs |
| `--extra` | `-x` | No | Extra args to pass in the message: key=value (value parsed as JSON with bigint support, fallback to string; repeated keys become arrays) |
| `--only-get-fee` | - | No | Print fee and exit |
| `--only-estimate` | - | No | Print gas estimate and exit |
| `--approve-max` | - | No | Approve max token amount instead of exact |
| `--wait` | - | No | Wait for execution on destination |

### `show <tx-hash-or-id>`

Show details of a CCIP request

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--log-index` | - | No | Pre-select a message request by logIndex, if more than one in tx; by default, a selection menu is shown |
| `--wait` | - | No | Wait for (first) execution |

### `getSupportedTokens` (aliases: get-supported-tokens)

List supported tokens in a given Router/OnRamp/TokenAdminRegistry, and/or show info about token/pool

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--network` | `-n` | Yes | Source network: chainId or name (e.g., ethereum-mainnet) |
| `--address` | `-a` | Yes | Router/OnRamp/TokenAdminRegistry/TokenPool contract address |
| `--token` | `-t` | No | Token address to query (pre-selects from list if address is a registry) |
| `--fee-tokens` | - | No | List fee tokens instead of transferable tokens; default=true for Routers; Use `--no-fee-tokens` to disable |
| `--only-fee-tokens` | - | No | Return after listing fee tokens |

### `token`

Query token balance for an address

| Option | Alias | Required | Description |
|--------|-------|----------|-------------|
| `--network` | `-n` | Yes | Network: chainId or name (e.g., ethereum-mainnet, solana-devnet) |
| `--holder` | `-H` | Yes | Wallet address to query balance for |
| `--token` | `-t` | No | Token address (omit for native token balance) |


---

## REST API Endpoints (8)

Base URL: `https://api.ccip.chain.link`

### `GET /messages/{messageId}`

**Summary:** Retrieve a single message

**Description:** Retrieve the current status and details of a CCIP cross-chain message.

**Use Cases:**
- Get complete message details
- Monitor message status from source to destination chain
- Verify successful execution on destination chain
- Check manual execution eligibility for messages

**How to obtain the messageId:**
- From a `ccipSend()` transaction log on the source chain
- Using the [`/messages`](#model-MessageSearchResult) search endpoint to find messages by sender, receiver, or chain


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `messageId` | path | string | Yes | The unique identifier of the message (64-character hex string with 0x prefix) |

**Responses:**

- `200`: The request was successful. Returns a [`Message`](#model-Message) object.

- `400`: Bad request - Invalid message ID format. Returns an [`Error`](#model-Error) object.

- `404`: Message not found. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /messages`

**Summary:** Retrieve multiple messages with filtering

**Description:** Search and filter CCIP messages with cursor-based pagination.
Results are ordered by send time (most recent first).

**Use Cases:**
- Filter by sender or receiver address
- Filter by source or destination chain
- Filter by messages ready for manual execution only
- Filter by source (send) transaction hash
- Filter by source token address
- General identifier search (**q**) — matches across several fields tied to a message (e.g. sender/receiver addresses, send/commit/receipt-related transaction hashes, message ID, token addresses etc.).

**q vs named query parameters**
- Use sender / receiver when results must be strictly **from** or **to** that address.
- Use sourceTransactionHash when the value is specifically the **source send** transaction hash.
- Use sourceTokenAddress when filtering by a token that appears in **transfers**.
- Use q for a single “paste an identifier” search, or when you are unsure which specific field holds the value, or when you have an address and want to find all messages it's involved in (as sender, receiver, token party, etc.).

**q with other filters**  
q can be combined with other filters (for example `q=0xabc...&sourceChainSelector=...`).

**Search behavior note**  
Because q spans several fields, a result may match the value in a different role than you expect (for example an address appearing as a token party rather than as sender).

**Search parameter constraints**
- You can use either cursor OR filter parameters (sender, receiver, sourceChainSelector, destChainSelector, readyForManualExecOnly, sourceTransactionHash, sourceTokenAddress, q), but NOT both simultaneously.
- limit can always be specified regardless of whether you're using cursor or filters.
- Violating constraints will return a 400 Bad Request.

**Usage examples**
- Filtered search: `/messages?sender=0x123...&limit=50`
- General search: `/messages?q=0xabc...,0xdef...&sourceChainSelector=...&limit=50`
- Next page: `/messages?cursor=WyJuYXR1cmFsIiwxMjM0NV0=&limit=20`
- Invalid (400): `/messages?sender=0x123...&cursor=WyJuYXR1cmFsIiwxMjM0NV0=`


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `limit` | query | integer | No | Maximum number of messages to return per page (default 100, max 1000). Can be used with either cursor or filters. |
| `cursor` | query | string | No | Pagination cursor returned from previous response (for fetching next page).
When using cursor, do not provide any filter parameters.
Providing both will result in a 400 Bad Request.
 |
| `sender` | query | string | No | Filter messages by sender address.
 |
| `receiver` | query | string | No | Filter messages by receiver address.
 |
| `sourceChainSelector` | query | string | No | Filter messages by source chain selector.
This is a uint64 value represented as a string.

For the complete list of chain selectors, see: [CCIP Directory](https://docs.chain.link/ccip/directory)
 |
| `destChainSelector` | query | string | No | Filter messages by destination chain selector.
This is a uint64 value represented as a string.

For the complete list of chain selectors, see: [CCIP Directory](https://docs.chain.link/ccip/directory)
 |
| `readyForManualExecOnly` | query | boolean | No | Filter to only messages ready for manual execution. When set to `true`, returns only messages
that are ready for manual execution. When set to `false` or omitted, returns all messages without filtering.
 |
| `sourceTransactionHash` | query | string | No | Filter messages by source transaction hash. Format depends on source chain family.
 |
| `sourceTokenAddress` | query | string | No | Filter messages by source token address. Returns messages that include
the specified token in their token transfers.
 |
| `q` | query | string | No | Comma-separated list of search terms. All listed identifiers must match.

**Note:** Since `q` matches across multiple fields, results may include messages where the value
matches in a different role than expected.
 |

**Responses:**

- `200`: The request was successful. Returns an array of [`MessageSearchResult`](#model-MessageSearchResult) objects with pagination metadata.

- `400`: Bad request - Invalid parameter format or constraint violation. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /messages/{messageId}/execution-inputs`

**Summary:** Retrieve execution inputs for a message

**Description:** Retrieve the execution input data needed to execute a specific CCIP message.
The response format depends on the lane version:

- **Lane version 1.6 and below**: Returns an array of encoded messages (all messages in the same commit batch as the desired one)
- **Lane version 2.0+**: Returns the encoded message along with verifier addresses, ccv data, and a `verificationComplete` boolean flag

**For lane version 2.0+ messages:**
- The endpoint always returns HTTP 200 with execution inputs, even if verification requirements are not yet satisfied
- Clients should check the `verificationComplete` field to determine if the message is ready for execution:
  - `true`: All required verifiers and optional threshold met. Ready for execution.
  - `false`: Verification requirements not yet satisfied. Additional verifications needed before execution.

**Use Cases:**
- Prepare data for message execution


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `messageId` | path | string | Yes | The unique identifier of the message (64-character hex string with 0x prefix) |

**Responses:**

- `200`: The request was successful. Returns execution input data in a format that depends on the lane version.
For lane version 1.6 and below, returns [`ExecutionInputsV1`](#model-ExecutionInputsV1).
For lane version 2.0+, returns [`ExecutionInputsV2`](#model-ExecutionInputsV2).

- `400`: Bad request - Invalid message ID format. Returns an [`Error`](#model-Error) object.

- `404`: Message not found. Returns an [`Error`](#model-Error) object.

- `409`: Conflict - The message exists but execution inputs cannot be provided yet.
This can occur when:
- The message has not been committed yet (no Merkle root available)

Retry the request later when the message has progressed further in its lifecycle.
Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /lanes/latency`

**Summary:** Retrieve lane latency

**Description:** Get the 90th percentile (p90) message delivery latency for a CCIP lane.

**Use Cases:**
- Estimate transfer times for UI display
- Monitor lane health and performance

**Note:** Latency is returned in milliseconds.


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `sourceChainSelector` | query | string | Yes | The CCIP chain selector for the source network.
This is a uint64 value represented as a string.

For the complete list of chain selectors, see: [CCIP Directory](https://docs.chain.link/ccip/directory)
 |
| `destChainSelector` | query | string | Yes | The CCIP chain selector for the destination network.
This is a uint64 value represented as a string.

For the complete list of chain selectors, see: [CCIP Directory](https://docs.chain.link/ccip/directory)
 |
| `numOfBlocks` | query | string | No | Optional number of block confirmations to use for lane latency estimation.
Defaults to 0, which means full chain finality is used instead.
 |

**Responses:**

- `200`: The request was successful. Returns a [`LaneLatency`](#model-LaneLatency) object.

- `400`: Bad request - Missing or invalid parameters. Returns an [`Error`](#model-Error) object.

- `404`: Lane not found. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /verifiers`

**Summary:** Retrieve available verifiers

**Description:** Get a list of all available CCIP verifiers and their metadata.

**Use Cases:**
- Display verifier options in UI
- Get verifier metadata


**Responses:**

- `200`: The request was successful. Returns a [`VerifiersResponse`](#model-VerifiersResponse) object containing the list of verifiers.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `POST /intents/quotes`

**Summary:** Create quote for intent

**Description:** Create a quote for a cross-chain swap or bridge operation.
Returns executable transaction data that can be submitted on-chain.


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `x-api-key` | header | string | No | API key to validate caller. This is not entirely public yet.
This may be required on some routes for some time.
 |

**Request Body:** `IntentQuoteRequest`

**Responses:**

- `200`: Quote generated successfully. Returns an [`IntentQuoteResponse`](#model-IntentQuoteResponse) object.

- `400`: Invalid request parameters. Returns an [`Error`](#model-Error) object.

- `401`: Unauthorized - Invalid or missing API key. Returns an [`Error`](#model-Error) object.

- `404`: No route available for the requested chain/token pair. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /intents/tx/{txHash}`

**Summary:** Get all intent statuses for a transaction

**Description:** Retrieve the status of all intents created in a specific transaction.
Supports batched intents where multiple intents are created in a single transaction.
This endpoint can be used to obtain intent IDs after initiating intent transactions.
Please favour using `/intents/id/{intentId}` to query intent status after obtaining the intent ID.


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `x-api-key` | header | string | No | API key to validate caller. This is not entirely public yet.
This may be required on some routes for some time.
 |
| `txHash` | path | string | Yes | Intent creation transaction hash |

**Responses:**

- `200`: Intent statuses retrieved successfully. Returns an array of [`IntentStatusResponse`](#model-IntentStatusResponse) objects.

- `401`: Unauthorized - Invalid or missing API key. Returns an [`Error`](#model-Error) object.

- `404`: Transaction not found. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.


### `GET /intents/id/{intentId}`

**Summary:** Get intent status by ID

**Description:** Retrieve the status of a specific intent by its intentId.

**Important**: Use the `intentId` returned by `/intents/tx/{txHash}`. Intent IDs
are provider-prefixed (e.g., `EC-...` or `EO-...`). Raw `0x...` transaction hashes
are not valid intent IDs - use `/intents/tx/{txHash}` to look up by transaction hash.


**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `x-api-key` | header | string | No | API key to validate caller. This is not entirely public yet.
This may be required on some routes for some time.
 |
| `intentId` | path | string | Yes | Unique intent identifier returned by `/intents/tx/{txHash}`.
Must be a provider-prefixed ID (e.g., `EC-...` or `EO-...`), not a raw `0x...` hash.
 |

**Responses:**

- `200`: Intent status retrieved successfully. Returns an [`IntentStatusResponse`](#model-IntentStatusResponse) object.

- `401`: Unauthorized - Invalid or missing API key. Returns an [`Error`](#model-Error) object.

- `404`: Intent not found. Returns an [`Error`](#model-Error) object.

- `500`: Internal server error. Returns an [`Error`](#model-Error) object.



---

## Documentation Links

### SDK Guides

- [Browser Setup](https://docs.chain.link/ccip/tools/sdk/guides/browser-setup)
- [Cancellation with AbortSignal](https://docs.chain.link/ccip/tools/sdk/guides/cancellation)
- [Error Handling](https://docs.chain.link/ccip/tools/sdk/guides/error-handling)
- [Error Reference](https://docs.chain.link/ccip/tools/sdk/guides/error-reference)
- [Fee Estimation](https://docs.chain.link/ccip/tools/sdk/guides/fee-estimation)
- [Faster-Than-Finality (FTF)](https://docs.chain.link/ccip/tools/sdk/guides/ftf)
- [Gas Estimation](https://docs.chain.link/ccip/tools/sdk/guides/gas-estimation)
- [Manual Execution](https://docs.chain.link/ccip/tools/sdk/guides/manual-execution)
- [Multi-Chain](https://docs.chain.link/ccip/tools/sdk/guides/multi-chain)
- [Querying Data](https://docs.chain.link/ccip/tools/sdk/guides/querying-data)
- [Searching Messages](https://docs.chain.link/ccip/tools/sdk/guides/searching-messages)
- [Sending Messages](https://docs.chain.link/ccip/tools/sdk/guides/sending-messages)
- [Token Pools](https://docs.chain.link/ccip/tools/sdk/guides/token-pools)
- [Tracking Messages](https://docs.chain.link/ccip/tools/sdk/guides/tracking-messages)
- [Viem Integration](https://docs.chain.link/ccip/tools/sdk/guides/viem-integration)

### CLI

- [Configuration](https://docs.chain.link/ccip/tools/cli/configuration)
- [CCIP CLI](https://docs.chain.link/ccip/tools/cli/index)
- [lane-latency](https://docs.chain.link/ccip/tools/cli/lane-latency)
- [manual-exec](https://docs.chain.link/ccip/tools/cli/manual-exec)
- [parse](https://docs.chain.link/ccip/tools/cli/parse)
- [search](https://docs.chain.link/ccip/tools/cli/search)
- [send](https://docs.chain.link/ccip/tools/cli/send)
- [show](https://docs.chain.link/ccip/tools/cli/show)
- [get-supported-tokens](https://docs.chain.link/ccip/tools/cli/supported-tokens)
- [token](https://docs.chain.link/ccip/tools/cli/token)
- [Troubleshooting](https://docs.chain.link/ccip/tools/cli/troubleshooting)

### CLI Guides

- [Transfer Data](https://docs.chain.link/ccip/tools/cli/guides/data-transfer-workflow)
- [Debugging Failed Messages](https://docs.chain.link/ccip/tools/cli/guides/debugging-workflow)
- [Token Transfer](https://docs.chain.link/ccip/tools/cli/guides/token-transfer-workflow)
- [Transfer Tokens and Data](https://docs.chain.link/ccip/tools/cli/guides/tokens-and-data-workflow)


---

## Quick Links

- **GitHub:** https://github.com/smartcontractkit/ccip-tools-ts
- **npm (SDK):** https://www.npmjs.com/package/@chainlink/ccip-sdk
- **npm (CLI):** https://www.npmjs.com/package/@chainlink/ccip-cli
- **CCIP Explorer:** https://ccip.chain.link
- **API Documentation:** https://api.ccip.chain.link/api-docs
- **CCIP Protocol Docs:** https://docs.chain.link/ccip
- **Full CCIP LLM Context:** https://docs.chain.link/ccip/llms-full.txt