Class: CCIPAPIClient

Defined in: api/index.ts:113

Client for interacting with the CCIP REST API.

Can be used standalone or injected into Chain classes.

Examples

TypeScript

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

TypeScript

const api = new CCIPAPIClient('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:128

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

Base URL for API requests

---

logger

readonly logger: Logger

Defined in: api/index.ts:117

Logger instance

---

timeoutMs

readonly timeoutMs: number

Defined in: api/index.ts:119

Request timeout in milliseconds

Methods

getLaneLatency()

getLaneLatency(sourceChainSelector: bigint, destChainSelector: bigint): Promise<LaneLatencyResponse>

Defined in: api/index.ts:205

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)

Returns

Promise<LaneLatencyResponse>

Promise resolving to LaneLatencyResponse with totalMs

Throws

CCIPLaneNotFoundError when lane not found (404)

Throws

CCIPTimeoutError if request times out

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

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): Promise<{ lane: Lane<CCIPVersion>; log: Log_; 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 | CCIPMessage_V1_6_TON; metadata: APICCIPRequestMetadata; tx: Pick<ChainTransaction, "hash" | "logs" | "blockNumber" | "timestamp" | "from" | "error">; }>

Defined in: api/index.ts:291

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")

Returns

Promise<{ lane: Lane<CCIPVersion>; log: Log_; 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 | CCIPMessage_V1_6_TON; metadata: APICCIPRequestMetadata; tx: Pick<ChainTransaction, "hash" | "logs" | "blockNumber" | "timestamp" | "from" | "error">; }>

Promise resolving to APICCIPRequest with message details

Throws

CCIPMessageIdNotFoundError when message not found (404)

Throws

CCIPTimeoutError if request times out

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.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): Promise<string[]>

Defined in: api/index.ts:354

Fetches message IDs from a source transaction hash.

Parameters

Parameter	Type	Description
txHash	string	Source transaction hash (EVM hex or Solana Base58)

Returns

Promise<string[]>

Promise resolving to array of message IDs

Throws

CCIPMessageNotFoundInTxError when no messages found (404 or empty)

Throws

CCIPUnexpectedPaginationError when hasNextPage is true

Throws

CCIPTimeoutError if request times out

Throws

CCIPHttpError on HTTP errors

Example

TypeScript

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

---

fromUrl()

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

Defined in: api/index.ts:142

Factory method for creating CCIPAPIClient. Currently equivalent to constructor; reserved for future preflight checks.

Parameters

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

Returns

Promise<CCIPAPIClient>

New CCIPAPIClient instance