Class: CCIPAPIClient

Defined in: api/index.ts:124

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

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

Base URL for API requests

---

logger

readonly logger: Logger

Defined in: api/index.ts:128

Logger instance

---

timeoutMs

readonly timeoutMs: number

Defined in: api/index.ts:130

Request timeout in milliseconds

Methods

getExecutionInput()

getExecutionInput(messageId: string): Promise<ExecutionInput & { offRamp: string; }>

Defined in: api/index.ts:443

Fetches the execution input for a given message by id.

Parameters

Parameter	Type	Description
messageId	string	The ID of the message to fetch the execution input for.

Returns

Promise<ExecutionInput & { offRamp: string; }>

Either { encodedMessage, verifications } or { message, offchainTokenData, ...proof }, and offRamp

---

getLaneLatency()

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

Defined in: api/index.ts:230

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: ChainLog; message: { 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[]; } | { 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; metadata: APICCIPRequestMetadata; tx: Omit<ChainTransaction, "logs">; }>

Defined in: api/index.ts:316

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: ChainLog; message: { 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[]; } | { 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; 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

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

Defined in: api/index.ts:379

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): CCIPAPIClient

Defined in: api/index.ts:161

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