ftUSD Circuit Breaker V2 — Limits, Capacity & Queue Endpoints (Frontend Integration Guide)

cb-limits-integration.md

Circuit Breaker V2 — Limits, Capacity & Queue Endpoints

New Endpoint: GET /status/ftusd/circuit-breaker/limits

Returns per-asset CB withdrawal capacity and rate limit data for all tracked assets. Use this to show "how much can user withdraw/redeem before hitting the CB rate limit" per token.

Query Params

Param	Required	Default	Description
chainId	no	146	Blockchain ID

Response

{
  "success": true,
  "chainId": 146,
  "circuitBreakerAddress": "0x5f19315ba3b54f3641c10d21006ef95f7b5f2cc6",
  "active": true,
  "paused": false,
  "settlementDelaySecs": 21600,
  "settlementDelayFormatted": "6:00:00",
  "assets": [
    {
      "address": "0x04e6...",
      "symbol": "ftUSD",
      "decimals": 6,
      "withdrawalCapacity": "500000000000",
      "withdrawalCapacityFormatted": "500.00K",
      "withdrawalCapacityNumeric": "500000",
      "totalCapacity": "1000000000000",
      "totalCapacityFormatted": "1.00M",
      "totalCapacityNumeric": "1000000",
      "mainBuffer": "800000000000",
      "mainBufferFormatted": "800.00K",
      "mainBufferNumeric": "800000",
      "mainBufferCap": "1200000000000",
      "mainBufferCapFormatted": "1.20M",
      "mainBufferCapNumeric": "1200000",
      "elasticBuffer": "200000000000",
      "elasticBufferFormatted": "200.00K",
      "elasticBufferNumeric": "200000",
      "pendingOutflows": "50000000",
      "pendingOutflowsFormatted": "50.0000",
      "pendingOutflowsNumeric": "50",
      "utilizationBps": 2000,
      "isPaused": false
    }
  ]
}

Key Fields for FE

• withdrawalCapacity — max amount (raw wei) user can withdraw RIGHT NOW without queuing
• withdrawalCapacityNumeric — same in token units, plain number (e.g. "500000")
• withdrawalCapacityFormatted — human-readable with suffix (e.g. "500.00K")
• totalCapacity — total buffer available (mainBuffer + elasticBuffer)
• utilizationBps — current utilization in basis points (2000 = 20%)
• settlementDelaySecs — how long queued operations take to settle (e.g. 21600 = 6h)

---

Enhanced: GET /status/ftusd/circuit-breaker/capacity

Now supports optional params for per-asset capacity checks.

Query Params

Param	Required	Default	Description
chainId	no	146	Blockchain ID
amount	no	—	Amount in wei to check. If omitted, returns just available capacity
asset	no	ftUSD addr	Hex address of asset to check capacity for

Response (with amount)

{
  "success": true,
  "asset": "0x04e6...",
  "wouldBeImmediate": true,
  "availableCapacity": "500000000000",
  "availableCapacityFormatted": "500.00K",
  "settlementDelaySecs": 21600,
  "settlementDelayFormatted": "6:00:00"
}

Response (without amount — capacity-only mode)

{
  "success": true,
  "asset": "0x04e6...",
  "availableCapacity": "500000000000",
  "availableCapacityFormatted": "500.00K",
  "settlementDelaySecs": 21600,
  "settlementDelayFormatted": "6:00:00"
}

Note: wouldBeImmediate is omitted when amount is not provided.

---

Existing: GET /status/ftusd/circuit-breaker/queue

Returns enriched queued outflows for a user.

Query Params

Param	Required	Default	Description
address	yes	—	User wallet address
chainId	no	146	Blockchain ID

Response

{
  "success": true,
  "outflows": [
    {
      "queueId": 42,
      "action": "redeem",
      "fromToken": { "address": "0x04e6...", "symbol": "ftUSD", "decimals": 6 },
      "fromAmount": "1000000",
      "fromAmountFormatted": "1.0000",
      "toToken": { "address": "0x2921...", "symbol": "USDC", "decimals": 6 },
      "toAmount": "999500",
      "toAmountFormatted": "0.9995",
      "recipient": "0xabc...",
      "queuedAt": 1739900000,
      "settlesAt": 1739921600,
      "status": "pending",
      "timeUntilSettled": 3600,
      "claimable": false,
      "transactionHash": "0xdef..."
    }
  ]
}

Action Types

Action	Meaning	fromToken	toToken
buy	Mint ftUSD with collateral	collateral	ftUSD
buyAndStake	Mint + stake into sftUSD	collateral	sftUSD
unstake	Unstake sftUSD to ftUSD	sftUSD	ftUSD
redeem	Burn ftUSD for collateral	ftUSD	collateral
unknown	Classification failed	—	—

Claimable Logic

claimable = (status == "pending") && (currentTime >= settlesAt)

---

TypeScript Types

// GET /status/ftusd/circuit-breaker/limits
interface LimitsResponse {
  success: boolean;
  chainId: number;
  circuitBreakerAddress: string;
  active: boolean;
  paused: boolean;
  settlementDelaySecs: number;
  settlementDelayFormatted: string;
  assets: AssetLimitData[];
}

interface AssetLimitData {
  address: string;
  symbol: string;
  decimals: number;
  withdrawalCapacity: string;            // raw wei
  withdrawalCapacityFormatted: string;   // "500.00K"
  withdrawalCapacityNumeric: string;     // "500000"
  totalCapacity: string;
  totalCapacityFormatted: string;
  totalCapacityNumeric: string;
  mainBuffer: string;
  mainBufferFormatted: string;
  mainBufferNumeric: string;
  mainBufferCap: string;
  mainBufferCapFormatted: string;
  mainBufferCapNumeric: string;
  elasticBuffer: string;
  elasticBufferFormatted: string;
  elasticBufferNumeric: string;
  pendingOutflows: string;
  pendingOutflowsFormatted: string;
  pendingOutflowsNumeric: string;
  utilizationBps: number;
  isPaused: boolean;
}

// GET /status/ftusd/circuit-breaker/capacity
interface CapacityCheckResponse {
  success: boolean;
  asset?: string;
  wouldBeImmediate?: boolean;  // only present when amount param provided
  availableCapacity: string;
  availableCapacityFormatted: string;
  settlementDelaySecs: number;
  settlementDelayFormatted: string;
}

// GET /status/ftusd/circuit-breaker/queue
interface QueueResponse {
  success: boolean;
  outflows: EnrichedQueuedOutflow[];
}

interface EnrichedQueuedOutflow {
  queueId: number;
  action: 'buy' | 'buyAndStake' | 'unstake' | 'redeem' | 'unknown';
  fromToken: TokenInfo;
  fromAmount: string;
  fromAmountFormatted: string;
  toToken: TokenInfo;
  toAmount: string;
  toAmountFormatted: string;
  recipient: string;
  queuedAt: number;
  settlesAt: number;
  status: 'pending' | 'executed' | 'paused';
  timeUntilSettled: number;
  claimable: boolean;
  transactionHash?: string;
}

interface TokenInfo {
  address: string;
  symbol: string;
  decimals: number;
}

Usage Example

// Check all CB limits for the UI
const limits = await fetch('/status/ftusd/circuit-breaker/limits?chainId=146')
  .then(r => r.json()) as LimitsResponse;

// Show per-asset: "You can redeem up to X ftUSD before hitting the rate limit"
for (const asset of limits.assets) {
  console.log(`${asset.symbol}: ${asset.withdrawalCapacityNumeric} available`);
  console.log(`  Utilization: ${asset.utilizationBps / 100}%`);
  console.log(`  Pending: ${asset.pendingOutflowsNumeric}`);
}

// Check if a specific redemption would go through immediately
const capacity = await fetch(
  '/status/ftusd/circuit-breaker/capacity?amount=1000000&chainId=146'
).then(r => r.json()) as CapacityCheckResponse;

if (capacity.wouldBeImmediate) {
  console.log('Redemption would be instant');
} else {
  console.log(`Would be queued. Settlement delay: ${capacity.settlementDelayFormatted}`);
}

// Get user's pending queue items
const queue = await fetch(
  '/status/ftusd/circuit-breaker/queue?address=0xabc...&chainId=146'
).then(r => r.json()) as QueueResponse;

const claimable = queue.outflows.filter(o => o.claimable);
console.log(`${claimable.length} items ready to claim`);

Field Naming Convention

• Raw (no suffix, e.g. withdrawalCapacity) — original wei/native unit string ("500000000000")
• *Formatted — human-readable with K/M/B suffixes ("500.00K")
• *Numeric — plain token-unit number, no suffixes ("500000")