@circle-fin/provider-fee-v1

[!IMPORTANT] This package is published for use within Circle's SDK packages. Its exports are marked @internal and are not currently a supported public API. They may change between releases without compatibility guarantees.

Applications should not import this package directly.

The package contains Circle Quote API integration used by Unified Balance Kit for FAST cross-chain deposits, including signed fee-quote retrieval and validation. The client wraps POST /v2/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).

Use @circle-fin/unified-balance-kit to estimate and execute deposits:

const estimate = await kit.estimateDeposit({
  from,
  amount: '10',
  token: 'USDC',
  to: { chain: 'Arc_Testnet' },
  config: { transferSpeed: 'FAST' },
})

const result = await kit.deposit({
  ...estimate,
  from,
})

Validating a signed quote

A signed quote is short-lived and bound to the exact on-chain call it will be submitted with. Before you burn, re-check it against the complete contract call via POST /v2/quote/validate/usdc/{sourceDomain}. validateQuote returns whether the quote is still claimable, the failedChecks blocking it (see QUOTE_REJECTION_REASONS), and the authoritative expiry status at the current source-chain tip.

import { validateQuote } from '@circle-fin/provider-fee-v1'

const result = await validateQuote({
  sourceDomain: 3, // Arbitrum CCTP domain
  // The exact function and arguments you will submit on-chain.
  abiSignature:
    'depositForBurnWithHookAndFees(uint256,uint32,bytes32,address,bytes32,bytes,(bytes,address))',
  args: [
    '1000000',
    '26',
    '0x0000000000000000000000001111111111111111111111111111111111111111',
    '0x2222222222222222222222222222222222222222',
    '0x0000000000000000000000000000000000000000000000000000000000000000',
    '0x636374702d666f72776172640000000000000000000000000000000000000000',
    ['0x01abcd', '0x3333333333333333333333333333333333333333'],
  ],
  isTestnet: false,
})

if (result.claimable) {
  console.log('safe to submit', result.expiry.secondsRemaining)
} else {
  console.warn('do not submit', result.failedChecks)
}

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 or expiry.expiresAtBlock); 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.