Class: CCIPAPIClient

Defined in: api/index.ts:141

Client for interacting with the CCIP REST API.

Can be used standalone or injected into Chain classes.

Examples

TypeScript

const api = CCIPAPIClient.fromUrl()
const latency = await api.getLaneLatency(sourceSelector, destSelector)
console.log(`Latency: ${latency.totalMs}ms`)

TypeScript

const api = CCIPAPIClient.fromUrl('https://custom.api.url', {
  logger: myLogger,
  fetch: myCustomFetch,
})

TypeScript

try {
  const latency = await api.getLaneLatency(sourceSelector, destSelector)
} catch (err) {
  if (err instanceof CCIPHttpError) {
    console.error(`API error ${err.context.status}: ${err.context.apiErrorMessage}`)
    if (err.isTransient) {
      // Retry after delay
    }
  }
}

Constructors

Constructor

new CCIPAPIClient(baseUrl?: string, ctx?: CCIPAPIClientContext): CCIPAPIClient

Defined in: api/index.ts:163

Creates a new CCIPAPIClient instance.

Parameters

Parameter	Type	Description
baseUrl?	string	Base URL for the CCIP API (defaults to DEFAULT_API_BASE_URL)
ctx?	CCIPAPIClientContext	Optional context with logger and custom fetch

Returns

CCIPAPIClient

Properties

baseUrl

readonly baseUrl: string

Defined in: api/index.ts:143

Base URL for API requests

---

logger

readonly logger: Logger

Defined in: api/index.ts:145

Logger instance

---

timeoutMs

readonly timeoutMs: number

Defined in: api/index.ts:147

Request timeout in milliseconds

Methods

getExecutionInput()

getExecutionInput(messageId: string, options?: { signal?: AbortSignal; }): Promise<ExecutionInput & Lane<CCIPVersion> & { offRamp: string; }>

Defined in: api/index.ts:670

Fetches the execution input for a given message by id. For v2.0 messages, returns { encodedMessage, verifications }. For pre-v2 messages, returns { message, offchainTokenData, proofs, ... } with merkle proof.

Parameters

Parameter	Type	Description
messageId	string	The CCIP message ID (32-byte hex string)
options?	{ signal?: AbortSignal; }	-
options.signal?	AbortSignal	-

Returns

Promise<ExecutionInput & Lane<CCIPVersion> & { offRamp: string; }>

Execution input with offRamp address and lane info

Throws

CCIPMessageIdNotFoundError when message not found (404)

Throws

CCIPTimeoutError if request times out

Throws

CCIPAbortError if request is aborted via signal

Throws

CCIPHttpError on other HTTP errors

Example

TypeScript

const api = CCIPAPIClient.fromUrl()
const execInput = await api.getExecutionInput('0x1234...')
// Use with dest.execute():
const { offRamp, ...input } = execInput
await dest.execute({ offRamp, input, wallet })

---

getLaneLatency()

getLaneLatency(sourceChainSelector: bigint, destChainSelector: bigint, numberOfBlocks?: number, options?: { signal?: AbortSignal; }): Promise<LaneLatencyResponse>

Defined in: api/index.ts:285

Fetches estimated lane latency between source and destination chains.

Parameters

Parameter	Type	Description
sourceChainSelector	bigint	Source chain selector (bigint)
destChainSelector	bigint	Destination chain selector (bigint)
numberOfBlocks?	number	Optional number of block confirmations for latency calculation. When omitted or 0, uses the lane's default finality. When provided as a positive integer, the API returns latency for that custom finality value (sent as numOfBlocks query parameter).
options?	{ signal?: AbortSignal; }	-
options.signal?	AbortSignal	-

Returns

Promise<LaneLatencyResponse>

Promise resolving to LaneLatencyResponse with totalMs

Throws

CCIPLaneNotFoundError when lane not found (404)

Throws

CCIPTimeoutError if request times out

Throws

CCIPAbortError if request is aborted via signal

Throws

CCIPHttpError on other HTTP errors with context:

• status - HTTP status code (e.g., 500)
• statusText - HTTP status message
• apiErrorCode - API error code (e.g., "INVALID_PARAMETERS")
• apiErrorMessage - Human-readable error message from API

Examples

TypeScript

const latency = await api.getLaneLatency(
  5009297550715157269n,  // Ethereum mainnet
  4949039107694359620n,  // Arbitrum mainnet
)
console.log(`Estimated delivery: ${Math.round(latency.totalMs / 60000)} minutes`)

TypeScript

const latency = await api.getLaneLatency(
  5009297550715157269n,  // Ethereum mainnet
  4949039107694359620n,  // Arbitrum mainnet
  10,                    // 10 block confirmations
)

TypeScript

try {
  const latency = await api.getLaneLatency(sourceSelector, destSelector)
} catch (err) {
  if (err instanceof CCIPHttpError && err.context.apiErrorCode === 'LANE_NOT_FOUND') {
    console.error('This lane does not exist')
  }
}

---

getMessageById()

getMessageById(messageId: string, options?: { signal?: AbortSignal; }): Promise<{ lane: Lane<CCIPVersion>; log: ChainLog; message: { data: string; feeToken: string; feeTokenAmount: bigint; gasLimit: bigint; messageId: string; nonce: bigint; receiver: string; sender: string; sequenceNumber: bigint; sourceChainSelector: bigint; sourceTokenData: readonly string[]; strict: boolean; tokenAmounts: readonly { amount: bigint; token: string; }[]; } | CCIPMessage_V1_5_EVM | CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui | { ccipReceiveGasLimit: number; ccvAndExecutorHash: string; data: string; destBlob: string; destChainSelector: bigint; encodedMessage: string; executionGasLimit: number; feeToken: string; feeTokenAmount: bigint; finality: number; messageId: string; messageNumber: bigint; offRampAddress: string; onRampAddress: string; receipts: readonly { destBytesOverhead: bigint; destGasLimit: bigint; extraArgs: string; feeTokenAmount: bigint; issuer: string; }[]; receiver: string; sender: string; sequenceNumber: bigint; sourceChainSelector: bigint; tokenAmountBeforeTokenPoolFees: bigint; tokenAmounts: readonly TokenTransferV1[]; verifierBlobs: readonly string[]; }; metadata: APICCIPRequestMetadata; tx: Omit<ChainTransaction, "logs">; }>

Defined in: api/index.ts:377

Fetches a CCIP message by its unique message ID.

Parameters

Parameter	Type	Description
messageId	string	The message ID (0x prefix + 64 hex characters, e.g., "0x1234...abcd")
options?	{ signal?: AbortSignal; }	-
options.signal?	AbortSignal	-

Returns

Promise<{ lane: Lane<CCIPVersion>; log: ChainLog; message: { data: string; feeToken: string; feeTokenAmount: bigint; gasLimit: bigint; messageId: string; nonce: bigint; receiver: string; sender: string; sequenceNumber: bigint; sourceChainSelector: bigint; sourceTokenData: readonly string[]; strict: boolean; tokenAmounts: readonly { amount: bigint; token: string; }[]; } | CCIPMessage_V1_5_EVM | CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui | { ccipReceiveGasLimit: number; ccvAndExecutorHash: string; data: string; destBlob: string; destChainSelector: bigint; encodedMessage: string; executionGasLimit: number; feeToken: string; feeTokenAmount: bigint; finality: number; messageId: string; messageNumber: bigint; offRampAddress: string; onRampAddress: string; receipts: readonly { destBytesOverhead: bigint; destGasLimit: bigint; extraArgs: string; feeTokenAmount: bigint; issuer: string; }[]; receiver: string; sender: string; sequenceNumber: bigint; sourceChainSelector: bigint; tokenAmountBeforeTokenPoolFees: bigint; tokenAmounts: readonly TokenTransferV1[]; verifierBlobs: readonly string[]; }; metadata: APICCIPRequestMetadata; tx: Omit<ChainTransaction, "logs">; }>

Promise resolving to APICCIPRequest with message details

Throws

CCIPMessageIdNotFoundError when message not found (404)

Throws

CCIPTimeoutError if request times out

Throws

CCIPAbortError if request is aborted via signal

Throws

CCIPHttpError on HTTP errors with context:

• status - HTTP status code
• statusText - HTTP status message
• apiErrorCode - API error code (e.g., "INVALID_MESSAGE_ID")
• apiErrorMessage - Human-readable error message

Examples

TypeScript

const request = await api.getMessageById(
  '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
)
console.log(`Status: ${request.metadata.status}`)
console.log(`From: ${request.message?.sender}`)

TypeScript

try {
  const request = await api.getMessageById(messageId)
} catch (err) {
  if (err instanceof CCIPMessageIdNotFoundError) {
    console.error('Message not found, it may still be in transit')
  }
}

---

getMessageIdsInTx()

getMessageIdsInTx(txHash: string, options?: { signal?: AbortSignal; }): Promise<string[]>

Defined in: api/index.ts:631

Fetches message IDs from a source transaction hash.

Parameters

Parameter	Type	Description
txHash	string	Source transaction hash.
options?	{ signal?: AbortSignal; }	-
options.signal?	AbortSignal	-

Returns

Promise<string[]>

Promise resolving to array of message IDs.

Remarks

Uses CCIPAPIClient.searchMessages internally with sourceTransactionHash filter and limit: 100.

Throws

CCIPMessageNotFoundInTxError when no messages found (404 or empty).

Throws

CCIPUnexpectedPaginationError when hasNextPage is true.

Throws

CCIPTimeoutError if request times out.

Throws

CCIPAbortError if request is aborted via signal.

Throws

CCIPHttpError on HTTP errors.

Examples

TypeScript

const messageIds = await api.getMessageIdsInTx(
  '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
)
console.log(`Found ${messageIds.length} messages`)

TypeScript

const api = CCIPAPIClient.fromUrl()
const messageIds = await api.getMessageIdsInTx(txHash)
for (const id of messageIds) {
  const request = await api.getMessageById(id)
  console.log(`${id}: ${request.metadata.status}`)
}

---

searchAllMessages()

searchAllMessages(filters?: MessageSearchFilters, options?: { limit?: number; signal?: AbortSignal; }): AsyncGenerator<MessageSearchResult>

Defined in: api/index.ts:582

Async generator that streams all messages matching the given filters, handling cursor-based pagination automatically.

Parameters

Parameter	Type	Description
filters?	MessageSearchFilters	Optional search filters (same as CCIPAPIClient.searchMessages).
options?	{ limit?: number; signal?: AbortSignal; }	Optional limit controlling the per-page fetch size (number of results fetched per API call). The total number of results is controlled by the consumer — break out of the loop to stop early.
options.limit?	number	-
options.signal?	AbortSignal	-

Returns

AsyncGenerator<MessageSearchResult>

AsyncGenerator yielding MessageSearchResult one at a time, across all pages.

Throws

CCIPTimeoutError if a page request times out.

Throws

CCIPAbortError if a page request is aborted via signal.

Throws

CCIPHttpError on HTTP errors (4xx/5xx, except 404 which yields nothing).

See

• CCIPAPIClient.searchMessages — for page-level control and explicit cursor handling
• CCIPAPIClient.getMessageById — fetch full message details for a search result

Examples

TypeScript

for await (const msg of api.searchAllMessages({ sender: '0x...' })) {
  console.log(`${msg.messageId}: ${msg.status}`)
}

TypeScript

const results: MessageSearchResult[] = []
for await (const msg of api.searchAllMessages({ sender: '0x...' })) {
  results.push(msg)
  if (results.length >= 5) break
}

---

searchMessages()

searchMessages(filters?: MessageSearchFilters, options?: { cursor?: string; limit?: number; signal?: AbortSignal; }): Promise<MessageSearchPage>

Defined in: api/index.ts:478

Searches CCIP messages using filters with cursor-based pagination.

Parameters

Parameter	Type	Description
filters?	MessageSearchFilters	Optional search filters. Ignored when options.cursor is provided (the cursor already encodes the original filters).
options?	{ cursor?: string; limit?: number; signal?: AbortSignal; }	Optional pagination options: limit (max results per page) and cursor (opaque token from a previous MessageSearchPage for the next page).
options.cursor?	string	-
options.limit?	number	-
options.signal?	AbortSignal	-

Returns

Promise<MessageSearchPage>

Promise resolving to a MessageSearchPage with results and pagination info.

Remarks

A 404 response is treated as "no results found" and returns an empty page, unlike CCIPAPIClient.getMessageById which throws on 404. When paginating with a cursor, the filters parameter is ignored because the cursor encodes the original filters.

Throws

CCIPTimeoutError if request times out.

Throws

CCIPAbortError if request is aborted via signal.

Throws

CCIPHttpError on HTTP errors (4xx/5xx, except 404 which returns empty).

See

• MessageSearchFilters — available filter fields
• MessageSearchPage — return type with pagination
• CCIPAPIClient.searchAllMessages — async generator that handles pagination automatically
• CCIPAPIClient.getMessageById — fetch full message details for a search result
• CCIPAPIClient.getMessageIdsInTx — convenience wrapper using sourceTransactionHash

Examples

TypeScript

const page = await api.searchMessages({
  sender: '0x9d087fC03ae39b088326b67fA3C788236645b717',
})
for (const msg of page.data) {
  console.log(`${msg.messageId}: ${msg.status}`)
}

TypeScript

let page = await api.searchMessages({ sender: '0x...' }, { limit: 10 })
const all = [...page.data]
while (page.hasNextPage) {
  page = await api.searchMessages(undefined, { cursor: page.cursor! })
  all.push(...page.data)
}

TypeScript

const page = await api.searchMessages({
  sender: '0x9d087fC03ae39b088326b67fA3C788236645b717',
  sourceChainSelector: 16015286601757825753n,
  destChainSelector: 14767482510784806043n,
})

---

fromUrl()

static fromUrl(baseUrl?: string, ctx?: CCIPAPIClientContext): CCIPAPIClient

Defined in: api/index.ts:194

Factory method for creating memoized CCIPAPIClient. Should be preferred over constructor, to avoid multiple fetch/retry/rate-limits instances, unless that's specifically required.

Parameters

Parameter	Type	Description
baseUrl?	string	Base URL for the CCIP API
ctx?	CCIPAPIClientContext	Optional context

Returns

CCIPAPIClient

New CCIPAPIClient instance