STABLECOIN ADAPTER

WHAT THIS PATTERN TEACHES

How to build a stablecoin treasury adapter: read wallet balances, initiate off-ramps (USDC to fiat), track transfer lifecycle through pending/settled/failed states, poll for settlement confirmation, and integrate with Circle's Business Account API as a reference implementation.

WHEN TO USE THIS

When your treasury uses stablecoin funding and needs to convert crypto to fiat for operational expenses like ad spend or vendor payments.

AT A GLANCE

interface StablecoinAdapter {
  getBalance(): Promise<BalanceCents>;
  initiateOfframp(amount: Cents): Promise<Transfer>;
  getTransferStatus(id: string): Promise<TransferState>;
}

FRAMEWORK IMPLEMENTATIONS

from enum import Enum
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import NewType
import httpx, asyncio

Cents = NewType("Cents", int)

class TransferState(str, Enum):
    PENDING_APPROVAL = "PENDING_APPROVAL"
    PENDING_SETTLEMENT = "PENDING_SETTLEMENT"
    SETTLED = "SETTLED"
    FAILED = "FAILED"

@dataclass(frozen=True)
class Transfer:
    id: str
    amount_cents: Cents
    state: TransferState
    destination_bank_id: str