Class: CCIPAPIClient

Defined in: api/index.ts:137

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:159

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:139

Base URL for API requests

---

logger

readonly logger: Logger

Defined in: api/index.ts:141

Logger instance

---

timeoutMs

readonly timeoutMs: number

Defined in: api/index.ts:143

Request timeout in milliseconds

Methods

getExecutionInput()

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

Defined in: api/index.ts:667

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; }	Optional request options. - signal — an AbortSignal to cancel the request.
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:271

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; }	Optional request options. - signal — an AbortSignal to cancel the request.
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: CCIPMessage_V1_5_EVM | { ccipReceiveGasLimit: number; ccvAndExecutorHash: string; data: string; destBlob: string; destChainSelector: bigint; encodedMessage: string; executionGasLimit: number; feeToken: string; feeTokenAmount: bigint; finality: FinalityRequested; 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[]; } | { 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_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui; metadata: APICCIPRequestMetadata; tx: Omit<ChainTransaction, "logs">; }>

Defined in: api/index.ts:365

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; }	Optional request options. - signal — an AbortSignal to cancel the request.
options.signal?	AbortSignal	-

Returns

Promise<{ lane: Lane<CCIPVersion>; log: ChainLog; message: CCIPMessage_V1_5_EVM | { ccipReceiveGasLimit: number; ccvAndExecutorHash: string; data: string; destBlob: string; destChainSelector: bigint; encodedMessage: string; executionGasLimit: number; feeToken: string; feeTokenAmount: bigint; finality: FinalityRequested; 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[]; } | { 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_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui; 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:626

Fetches message IDs from a source transaction hash.

Parameters

Parameter	Type	Description
txHash	string	Source transaction hash.
options?	{ signal?: AbortSignal; }	Optional request options. - signal — an AbortSignal to cancel the request.
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:575

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 request options: - limit — 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. - signal — an AbortSignal that, when aborted, cancels the next page fetch.
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:468

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 and request options: - limit — max results per page. - cursor — opaque token from a previous MessageSearchPage for the next page. - signal — an AbortSignal to cancel the request.
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:190

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