@usdctofiat/offramp

USDC-to-fiat offramp SDK for Base. 6 functions + 2 const objects.

Agent bundle

If you are integrating through an agent (Claude Code, Cursor, etc.), start here:

• Developer portal: https://usdctofiat.xyz/developers
• Drop-in skill: https://usdctofiat.xyz/skills/usdctofiat.md
• Short machine reference: https://usdctofiat.xyz/llms.txt
• Full machine reference: https://usdctofiat.xyz/llms-full.txt
• Scaffold CLI: npx create-offramp-app@latest my-app --template=next|vite|telegram-bot
• Starters (Next.js / Vite / Telegram bot, plus runnable example scripts and HMAC verifiers): https://github.com/ADWilkinson/usdctofiat-peerlytics-starters
• Companion SDK for analytics + explorer: @peerlytics/sdk (one Peerlytics API key authenticates both products)

Install

bun add @usdctofiat/offramp

Quick Start

import { offramp, PLATFORMS, CURRENCIES } from "@usdctofiat/offramp";

const result = await offramp(walletClient, {
  amount: "100",
  platform: PLATFORMS.REVOLUT,
  currency: CURRENCIES.EUR,
  identifier: "alice",
});
// { depositId: "362", txHash: "0x...", resumed: false }

Deposit Management

import { deposits, close } from "@usdctofiat/offramp";

const list = await deposits("0xYourAddress");
await close(walletClient, "361");

React

import { useOfframp } from "@usdctofiat/offramp/react";
import { PLATFORMS, CURRENCIES } from "@usdctofiat/offramp";

function SellButton({ walletClient }: { walletClient: WalletClient }) {
  const { offramp, step, isLoading } = useOfframp();

  return (
    <button
      disabled={isLoading}
      onClick={() => offramp(walletClient, {
        amount: "100",
        platform: PLATFORMS.REVOLUT,
        currency: CURRENCIES.EUR,
        identifier: "alice",
      })}
    >
      {step ?? "Sell USDC"}
    </button>
  );
}

Platform & Currency Data

import { PLATFORMS, CURRENCIES } from "@usdctofiat/offramp";

PLATFORMS.REVOLUT.name; // "Revolut"
PLATFORMS.REVOLUT.currencies; // ["USD", "EUR", "GBP", ...]
PLATFORMS.REVOLUT.identifier.label; // "Revtag"
PLATFORMS.REVOLUT.identifier.placeholder; // "revtag (no @)"
PLATFORMS.REVOLUT.identifier.help; // "Revtag without @ (must be public)"
PLATFORMS.REVOLUT.validate("@alice"); // { valid: true, normalized: "alice" }

CURRENCIES.EUR.symbol; // "€"
CURRENCIES.EUR.name; // "Euro"
CURRENCIES.EUR.countryCode; // "eu"

OTC Private Orders

Restrict a deposit to a single taker wallet. Pass otcTaker and the deposit is created, delegated, and restricted in one call:

import { offramp, PLATFORMS, CURRENCIES } from "@usdctofiat/offramp";

const { depositId, otcLink } = await offramp(walletClient, {
  amount: "100",
  platform: PLATFORMS.REVOLUT,
  currency: CURRENCIES.EUR,
  identifier: "alice",
  otcTaker: "0xBuyerAddress",
});
// otcLink = "https://otc.usdctofiat.xyz/d/0x.../362"
// Share otcLink with the buyer — they open it, connect their wallet, and fill the order.

Toggle OTC on existing deposits:

import { enableOtc, disableOtc, getOtcLink } from "@usdctofiat/offramp";

await enableOtc(walletClient, "362", "0xBuyerAddress");
await disableOtc(walletClient, "362"); // make public again
getOtcLink("362"); // just the URL, no tx

Resumable

offramp() is idempotent. If an undelegated deposit exists for the wallet, it skips straight to delegation. Handles browser crashes, failed delegation, and retries automatically. Just call offramp() again.

Error Handling

import { OfframpError, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";

try {
  await offramp(walletClient, params);
} catch (err) {
  if (err instanceof OfframpError) {
    if (err.code === "USER_CANCELLED") return;
    if (err.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED) {
      // User needs to register in the Peer extension first — see below.
      return;
    }
    // For any other failure: call offramp() again to resume
  }
}

Peer Extension Registration (PayPal, Wise)

PayPal and Wise makers must register their handle inside the Peer (PeerAuth) browser extension before the first deposit. The SDK throws OfframpError with code EXTENSION_REGISTRATION_REQUIRED when curator rejects a maker for this reason. Drive the three-step handshake via the React hook:

import { PLATFORMS, CURRENCIES, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";
import { useOfframp, usePeerExtensionRegistration } from "@usdctofiat/offramp/react";

function PayPalSellButton({ walletClient }) {
  const { offramp, lastError } = useOfframp();
  const peer = usePeerExtensionRegistration(PLATFORMS.PAYPAL);

  const needsExtension = lastError?.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED;

  return (
    <>
      <button
        onClick={() =>
          offramp(walletClient, {
            amount: "100",
            platform: PLATFORMS.PAYPAL,
            currency: CURRENCIES.USD,
            identifier: "alicepay", // PayPal.me username, NOT email
          })
        }
      >
        Sell USDC
      </button>

      {needsExtension && (
        <div>
          <p>{peer.info?.requiredPrompt}</p>
          {peer.phase === "needs_install" && (
            <button onClick={peer.installExtension}>Install Peer Extension</button>
          )}
          {peer.phase === "needs_connection" && (
            <button onClick={peer.connectExtension} disabled={peer.busy}>
              Connect Peer Extension
            </button>
          )}
          {peer.phase === "ready" && (
            <button onClick={peer.openVerifySidebar}>Verify in Peer</button>
          )}
          {peer.info?.ctaSubtext && <small>{peer.info.ctaSubtext}</small>}
        </div>
      )}
    </>
  );
}

Or drive the handshake manually via peerExtensionSdk:

import { peerExtensionSdk } from "@usdctofiat/offramp";

const state = await peerExtensionSdk.getState();
if (state === "needs_install") {
  peerExtensionSdk.openInstallPage();
} else if (state === "needs_connection") {
  const approved = await peerExtensionSdk.requestConnection();
  if (approved) peerExtensionSdk.openSidebar("/verify/paypal");
} else {
  peerExtensionSdk.openSidebar("/verify/paypal");
}

After the user completes the flow in the extension, call offramp() again.

How It Works

Every deposit is automatically delegated to the Delegate vault for oracle-based rate management, auto-closes when filled, and is attributed to Galleon Labs via ERC-8021.

Webhooks

Subscribe to live deposit.created, deposit.filled, deposit.partially_filled, deposit.closed, and otc.taken events for your attributed deposits. otc.enabled and otc.disabled are reserved event names. Register endpoints at usdctofiat.xyz/developers with your Peerlytics API key. HMAC-SHA256 signed deliveries use the X-Usdctofiat-Signature: t=<unix>,v1=<hex> header. Reference HMAC receiver in the starters repo.

Links

usdctofiat.xyz · delegate.usdctofiat.xyz · peerlytics.xyz · orderbook.peerlytics.xyz

Examples & agent skills · @usdctofiat · @andrewwilkinson