@circle-fin/provider-fee-v1

Fee-quote client for Circle's Quote API (hosted in Iris). It fetches a signed quote for the prepaid FORWARD fast-deposit path, the price source for a cross-chain CCTP v2 burn submitted through TokenMessengerWithFees. There is no on-chain fee oracle: the signed quote returned here is passed verbatim into the on-chain QuoteClaim.

The client wraps POST /v1/quote/burn/usdc/{sourceDomain}/{destinationDomain}. The endpoint is permissionless (no auth) and edge rate-limited, and is feature-flagged per source chain (a disabled chain returns 503 SERVICE_NOT_ENABLED, surfaced as a fatal, non-retryable error).

Usage

import {
  fetchFeeQuote,
  hydrateForwardRequest,
} from '@circle-fin/provider-fee-v1'

// Bind the FORWARD quote to the EXACT hookData you will burn with on-chain.
// The signed quote covers these bytes; submitting different bytes reverts.
// This is the full 32-byte cctp-forward-framed hookData: the 12-byte
// "cctp-forward" prefix right-padded to 24 bytes, then a uint32 version and a
// uint32 length. It matches what `buildForwardingHookData()` produces.
const requests = hydrateForwardRequest(
  [{ type: 'FORWARD' }, { type: 'PRE_FINALITY' }],
  {
    hookData:
      '0x636374702d666f72776172640000000000000000000000000000000000000000',
    destinationCaller: '0xFa7be2f04F3Ad4ca969260729c6d45B5625984A7',
  },
)

const quote = await fetchFeeQuote({
  sourceDomain: 3, // Arbitrum CCTP domain
  destinationDomain: 26, // Arc CCTP domain
  amount: '1000000', // 1 USDC, in minor units
  requests,
  isTestnet: false,
})

console.log(quote.feeTotalAmount, quote.feeToken, quote.expiry.expiresAt)
// quote.signedQuote -> the on-chain QuoteClaim (kept out of logs).

Notes

• amount is a decimal string in token minor units.
• feeToken defaults to the zero address (native); pass a USDC address to pay fees in USDC.
• The quote is short-lived (expiry.expiresAt / expiry.mode); fetch a fresh quote immediately before submitting on-chain rather than caching it.
• signedQuote is opaque bytes returned verbatim; do not decode it.
• The client makes a single attempt (no transport retry/backoff). The endpoint is edge rate-limited, so on a 429 the caller should back off and re-request rather than expecting the client to retry.