Check CCTP Transfer Status — GET /api/cctp/transfer/status

Poll the progress of a CCTP bridge transfer initiated via POST /api/cctp/transfer. Pass the bridge_... reference returned by that call as the reference query parameter. This endpoint is public — no authentication is required.

Testnet/development flow. CCTP status values describe bridging into Arc Testnet. FlareHQ production runs on Arc Mainnet (chain ID 5042) — mainnet CCTP bridging is not claimed here.

It re-checks in-flight transfers through Circle Bridge Kit’s own retry() mechanism, so each poll advances the transfer toward completion rather than merely reading a cached state.

Endpoint

GET https://flarehq.xyz/api/cctp/transfer/status

Request

Headers

Header	Value
`x-api-key`	Not required — this endpoint is public. No authentication is needed.

Query Parameters

string

required

The bridge_... reference returned by POST /api/cctp/transfer.

Response

The response shape depends on the transfer’s current stage. All successful responses include "success": true.

boolean

true when the reference was found and its state read successfully.

string

Current bridge state. One of:

"submitting" — the source-chain burn transaction is still being submitted; no result yet.
"pending" — the burn is submitted but Circle’s relayer has not yet minted on Arc.
"success" — the bridge completed; USDC has arrived on Arc.
"error" — the bridge failed; check the error field.

string

Present only when state is "error". Human-readable reason for the failure.

When the transfer has settled, the response additionally includes:

string

The USDC amount that was bridged, as returned by Bridge Kit.

string | undefined

Explorer URL for the source-chain burn transaction. Omitted when the burn step is not yet finalized.

string | undefined

Explorer URL for the destination mint transaction on Arc (e.g. https://testnet.arcscan.app/tx/{hash}). Omitted when the mint step is not yet finalized.

Examples

curl "https://flarehq.xyz/api/cctp/transfer/status?reference=bridge_lx4m9q2t7w8k3p0ab5"

const res = await fetch(
  'https://flarehq.xyz/api/cctp/transfer/status?reference=bridge_lx4m9q2t7w8k3p0ab5'
);

const { success, state, amount, sourceExplorerUrl, destinationExplorerUrl } = await res.json();
// state: 'submitting' | 'pending' | 'success' | 'error'

Success Response — Submitting

{
  "success": true,
  "state": "submitting"
}

Success Response — Settled

{
  "success": true,
  "state": "success",
  "amount": "100.00",
  "sourceExplorerUrl": "https://sepolia.etherscan.io/tx/0x9f2a...",
  "destinationExplorerUrl": "https://testnet.arcscan.app/tx/0x4c8e..."
}

Success Response — Failed

{
  "success": true,
  "state": "error",
  "error": "Circle attestation timed out."
}

Error Responses

{
  "success": false,
  "error": "reference query param is required."
}

{
  "success": false,
  "error": "No bridge found for that reference (it may have already completed, or the server restarted)."
}

Notes

The bridge_... reference is tracked in process memory, not a database. If the server restarts before the transfer settles, subsequent polls return HTTP 404 — the in-flight transfer cannot be resumed through this endpoint after a restart.

Poll in a loop with a short interval (for example every 15–30 seconds) until state reaches "success" or "error". Each poll triggers Bridge Kit’s retry() on the underlying transfer, which nudges the destination mint forward rather than just reporting a stale state.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Check CCTP Transfer Status — GET /api/cctp/transfer/status

Endpoint

Request

Headers

Query Parameters

Response

Examples

Success Response — Submitting

Success Response — Settled

Success Response — Failed

Error Responses

Notes

​Endpoint

​Request

​Headers

​Query Parameters

​Response

​Examples

​Success Response — Submitting

​Success Response — Settled

​Success Response — Failed

​Error Responses

​Notes

Endpoint

Request

Headers

Query Parameters

Response

Examples

Success Response — Submitting

Success Response — Settled

Success Response — Failed

Error Responses

Notes