OpenAPI Specification
openapi: 3.0.0
info:
title: Enso ccip cctp API
description: '#### Enso API
- Find detailed documentation on [docs.enso.finance](https://docs.enso.finance).
- To use the API, **you must include your API Key in the Authorization header** (Bearer format).
- For testing, Swagger pre-authorizes you using the key: `1e02632d-6feb-4a75-a157-documentation` (1rps).
- Get your own API Key at [enso.finance/developers](https://developers.enso.build/).'
version: '1.0'
contact: {}
servers:
- url: https://api.enso.finance
security:
- bearer: []
tags:
- name: cctp
paths:
/api/v1/cctp/bridge/check:
get:
operationId: CctpController_checkBridgeTransaction
summary: Check CCTP bridge transaction status
description: Returns information about a cross-chain CCTP bridge transaction, including attestation status, amount, fee, and destination transaction. Rate limited to 1 request per 10 seconds.
parameters:
- name: chainId
required: true
in: query
description: Chain ID of the source transaction
schema:
example: 143
type: number
- name: txHash
required: true
in: query
description: Transaction hash of the CCTP bridge transaction on source chain
schema:
example: '0x4ac72089eef92b827702281bb2668b416ee6d3e9d953600dc363842e473a157c'
type: string
responses:
'200':
description: Bridge transaction status and details
content:
application/json:
schema:
$ref: '#/components/schemas/CctpBridgeTransactionResponse'
'429':
description: Rate limit exceeded (max 1 request per 10 seconds)
tags:
- cctp
/api/v1/cctp/bridge/tokenmessengerv2:
get:
operationId: CctpController_getTokenMessenger
summary: Get TokenMessengerV2 address for a chain
description: Returns the CCTP TokenMessengerV2 contract address for the specified chain.
parameters:
- name: chainId
required: true
in: query
description: Chain ID
schema:
example: 1
type: number
responses:
'200':
description: TokenMessengerV2 address
content:
application/json:
schema:
$ref: '#/components/schemas/CctpTokenMessengerResponse'
'400':
description: Chain not supported by CCTP
tags:
- cctp
/api/v1/cctp/bridge/claim:
get:
operationId: CctpController_getClaimTx
summary: Generate claim transaction for a CCTP bridge transfer
description: Returns a ready-to-submit receiveMessage transaction for the destination chain if the attestation is complete and the transfer has not been claimed yet. Rate limited to 1 request per 10 seconds.
parameters:
- name: chainId
required: true
in: query
description: Chain ID of the source transaction
schema:
example: 143
type: number
- name: txHash
required: true
in: query
description: Transaction hash of the CCTP bridge transaction on source chain
schema:
example: '0x4ac72089eef92b827702281bb2668b416ee6d3e9d953600dc363842e473a157c'
type: string
responses:
'200':
description: Claim transaction or reason why not claimable
content:
application/json:
schema:
$ref: '#/components/schemas/CctpClaimResponse'
'429':
description: Rate limit exceeded (max 1 request per 10 seconds)
tags:
- cctp
components:
schemas:
TokenInfo:
type: object
properties:
address:
type: string
description: Token contract address
example: '0x55d398326f99059fF775485246999027B3197955'
symbol:
type: string
description: Token symbol (e.g., USDT, USDC)
example: USDT
name:
type: string
description: Token full name
example: Tether USD
decimals:
type: number
description: Token decimals
example: 18
required:
- address
DepositForBurnWithHookParams:
type: object
properties:
amount:
type: string
description: Amount in token subunits
example: '100000'
destinationDomain:
type: number
description: CCTP destination domain ID
example: 0
mintRecipient:
type: string
description: Mint recipient as bytes32
example: '0x00000000000000000000000042d023187acedd3306e3dce2f1b9e4a81d636503'
burnToken:
type: string
description: Burn token address on source chain
example: '0x754704bc059f8c67012fed69bc8a327a5aafb603'
destinationCaller:
type: string
description: Destination caller restriction (bytes32(0) = anyone)
example: '0x0000000000000000000000000000000000000000000000000000000000000000'
maxFee:
type: string
description: Maximum fee in token subunits
example: '0'
minFinalityThreshold:
type: number
description: Minimum finality threshold
example: 1000
hookData:
type: string
description: Raw hookData bytes
example: '0x636374702d666f72776172640000000000000000000000000000000000000000'
required:
- amount
- destinationDomain
- mintRecipient
- burnToken
- destinationCaller
- maxFee
- minFinalityThreshold
- hookData
CctpTokenMessengerResponse:
type: object
properties:
address:
type: string
description: TokenMessengerV2 contract address on the specified chain
example: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d'
required:
- address
HookDataInfo:
type: object
properties:
raw:
type: string
description: Raw hookData bytes
example: '0x636374702d666f72776172640000000000000000000000000000000000000000'
forwardingService:
type: boolean
description: Whether the hookData payload matches Circle's Forwarding Service "cctp-forward" magic bytes.
example: true
hyperCoreTransfer:
type: boolean
description: True when the hookData is the 56-byte HyperCore forwarding payload (forwards the mint into HyperCore via the CctpForwarder).
example: true
hyperCoreRecipient:
type: string
description: HyperCore recipient decoded from the forwarding hookData (present for HyperCore transfers).
example: '0x42d023187acedd3306e3dce2f1b9e4a81d636503'
hyperCoreDestinationDex:
type: number
description: Raw destinationDex from the HyperCore hookData (0 = perps, 4294967295 = spot).
example: 4294967295
hyperCoreDestinationDexType:
type: string
description: Human-readable HyperCore destination DEX.
enum:
- perps
- spot
- unknown
example: spot
required:
- raw
- forwardingService
DepositForBurnParams:
type: object
properties:
amount:
type: string
description: Amount in token subunits
example: '100000'
destinationDomain:
type: number
description: CCTP destination domain ID
example: 0
mintRecipient:
type: string
description: Mint recipient as bytes32
example: '0x00000000000000000000000042d023187acedd3306e3dce2f1b9e4a81d636503'
burnToken:
type: string
description: Burn token address on source chain
example: '0x754704bc059f8c67012fed69bc8a327a5aafb603'
destinationCaller:
type: string
description: Destination caller restriction (bytes32(0) = anyone)
example: '0x0000000000000000000000000000000000000000000000000000000000000000'
maxFee:
type: string
description: Maximum fee in token subunits
example: '0'
minFinalityThreshold:
type: number
description: Minimum finality threshold
example: 1000
required:
- amount
- destinationDomain
- mintRecipient
- burnToken
- destinationCaller
- maxFee
- minFinalityThreshold
EnsoEvent:
type: object
properties:
accountId:
type: string
description: Account ID from ShortcutExecuted event
requestId:
type: string
description: Request ID from ShortcutExecuted event
blockNumber:
type: number
description: Block number where the event was emitted
transactionHash:
type: string
description: Transaction hash
chainId:
type: number
description: Chain ID where the event was emitted
success:
type: boolean
description: Whether the shortcut execution was successful
error:
type: string
description: Error data if execution failed
refundDetails:
description: Refund details if execution failed and funds were returned
allOf:
- $ref: '#/components/schemas/RefundDetails'
required:
- blockNumber
- transactionHash
- chainId
- success
FinalityInfo:
type: object
properties:
value:
type: number
description: Raw finality threshold value
example: 1000
type:
type: string
description: 'Transfer type: fast (<= 1000) or standard (>= 2000)'
enum:
- fast
- standard
example: fast
required:
- value
- type
CctpClaimTransaction:
type: object
properties:
to:
type: string
data:
type: string
value:
type: string
chainId:
type: number
required:
- to
- data
- value
- chainId
TokenAmount:
type: object
properties:
token:
description: Token information
allOf:
- $ref: '#/components/schemas/TokenInfo'
amount:
type: string
description: Token amount (in wei/smallest unit)
example: '1000000000000000000'
required:
- token
- amount
DepositForBurnWithHookDecoded:
type: object
properties:
burnToken:
$ref: '#/components/schemas/TokenAmount'
destinationChainId:
type: number
description: Destination chain ID
example: 1
mintRecipient:
type: string
description: Recipient address on destination chain (decoded from bytes32)
example: '0x42d023187acedd3306e3dce2f1b9e4a81d636503'
destinationCaller:
type: string
description: Destination caller as EVM address (decoded from bytes32)
example: '0x0000000000000000000000000000000000000000'
maxFee:
description: Maximum fee with token info
allOf:
- $ref: '#/components/schemas/TokenAmount'
minFinalityThreshold:
description: Requested finality threshold and type
allOf:
- $ref: '#/components/schemas/FinalityInfo'
finalityThresholdExecuted:
description: Actual finality threshold executed by Circle (may differ from requested)
allOf:
- $ref: '#/components/schemas/FinalityInfo'
feeExecuted:
description: Actual fee deducted from minted amount, with token info
allOf:
- $ref: '#/components/schemas/TokenAmount'
hookData:
description: hookData payload. `forwardingService` is true when the bytes match Circle's "cctp-forward" magic.
allOf:
- $ref: '#/components/schemas/HookDataInfo'
required:
- burnToken
- destinationChainId
- mintRecipient
- destinationCaller
- maxFee
- minFinalityThreshold
- hookData
CctpClaimResponse:
type: object
properties:
claimable:
type: boolean
description: Whether the claim transaction is available
example: true
destinationChainId:
type: number
description: Destination chain ID where receiveMessage should be called
example: 1
tx:
description: Ready-to-submit transaction to call MessageTransmitterV2.receiveMessage on the destination chain
allOf:
- $ref: '#/components/schemas/CctpClaimTransaction'
reason:
type: string
description: Reason if not claimable
example: Already claimed
required:
- claimable
DepositForBurnDecoded:
type: object
properties:
burnToken:
$ref: '#/components/schemas/TokenAmount'
destinationChainId:
type: number
description: Destination chain ID
example: 1
mintRecipient:
type: string
description: Recipient address on destination chain (decoded from bytes32)
example: '0x42d023187acedd3306e3dce2f1b9e4a81d636503'
destinationCaller:
type: string
description: Destination caller as EVM address (decoded from bytes32)
example: '0x0000000000000000000000000000000000000000'
maxFee:
description: Maximum fee with token info
allOf:
- $ref: '#/components/schemas/TokenAmount'
minFinalityThreshold:
description: Requested finality threshold and type
allOf:
- $ref: '#/components/schemas/FinalityInfo'
finalityThresholdExecuted:
description: Actual finality threshold executed by Circle (may differ from requested)
allOf:
- $ref: '#/components/schemas/FinalityInfo'
feeExecuted:
description: Actual fee deducted from minted amount, with token info
allOf:
- $ref: '#/components/schemas/TokenAmount'
required:
- burnToken
- destinationChainId
- mintRecipient
- destinationCaller
- maxFee
- minFinalityThreshold
CctpBridgeTransactionResponse:
type: object
properties:
sourceChainId:
type: number
description: Source chain ID where the CCTP burn was initiated
example: 143
sourceTxHash:
type: string
description: Source chain transaction hash
example: '0x4ac72089eef92b827702281bb2668b416ee6d3e9d953600dc363842e473a157c'
destinationChainId:
type: number
description: Destination chain ID where the mint occurs
example: 1
destinationTxHash:
type: string
description: Destination chain transaction hash (if mint has completed)
status:
type: string
description: Overall bridge status
enum:
- pending
- inflight
- delivered
- failed
- unknown
transferType:
type: string
description: 'CCTP transfer type based on finalityThresholdExecuted: "fast" (<= 1000) or "standard" (>= 2000)'
enum:
- fast
- standard
delayReason:
type: string
description: Reason Circle reports for delayed message processing (insufficient_fee, amount_above_max, insufficient_allowance_available).
example: insufficient_fee
forward:
description: Forwarding Service status for transfers with a forwarding hook (incl. HyperCore deposits). The bridge is only 'delivered' once the forward completes.
allOf:
- $ref: '#/components/schemas/ForwardingStatusInfo'
depositForBurn:
description: Raw depositForBurn function parameters. Present iff the source-chain call was plain depositForBurn (no hookData).
allOf:
- $ref: '#/components/schemas/DepositForBurnParams'
depositForBurnDecoded:
description: Decoded depositForBurn parameters with token metadata, chain IDs, and human-readable values.
allOf:
- $ref: '#/components/schemas/DepositForBurnDecoded'
depositForBurnWithHook:
description: Raw depositForBurnWithHook function parameters. Present iff the source-chain call was depositForBurnWithHook (non-empty hookData).
allOf:
- $ref: '#/components/schemas/DepositForBurnWithHookParams'
depositForBurnWithHookDecoded:
description: Decoded depositForBurnWithHook parameters with token metadata, chain IDs, and human-readable values.
allOf:
- $ref: '#/components/schemas/DepositForBurnWithHookDecoded'
ensoSourceEvent:
description: Enso shortcut event from source chain (ShortcutExecuted + execution result). Null if not found.
nullable: true
allOf:
- $ref: '#/components/schemas/EnsoEvent'
error:
type: string
description: Error message if the check failed
required:
- sourceChainId
- sourceTxHash
- status
ForwardingStatusInfo:
type: object
properties:
state:
type: string
description: Raw forward state reported by Circle's Forwarding Service (e.g. PENDING, COMPLETED, FAILED). Present only for forwarding-service transfers (incl. HyperCore deposits).
example: FAILED
errorCode:
type: string
description: Error code when the forward failed (e.g. INSUFFICIENT_FEE).
example: INSUFFICIENT_FEE
errorDetails:
type: string
description: Human-readable details when the forward failed.
example: Fee provided insufficient for forwarding
txHash:
type: string
description: Transaction hash of the forward (mint) transaction on the destination chain.
required:
- state
RefundDetails:
type: object
properties:
token:
type: string
description: Token address (0xeee... for native token)
amount:
type: string
description: Amount refunded
recipient:
type: string
description: Recipient address
isNative:
type: boolean
description: Whether the refund is in native token
required:
- token
- amount
- recipient
- isNative
securitySchemes:
bearer:
scheme: bearer
bearerFormat: apiKey
type: http