# USDCtoFiat

Non-custodial peer-to-peer USDC ↔ fiat surface for the ZKP2P protocol on Base.

## Agent bundle (read these first)

- SDK: `@usdctofiat/offramp` on npm — <https://www.npmjs.com/package/@usdctofiat/offramp>
- CLI scaffolder: `npx create-offramp-app@latest my-app --template=next|vite|telegram-bot`
- Full machine reference: <https://usdctofiat.xyz/llms-full.txt>
- Claude Code / agent skill: <https://usdctofiat.xyz/skills/usdctofiat.md>
- Starter templates: <https://github.com/ADWilkinson/usdctofiat-peerlytics-starters>
- Companion skill for market data + analytics: <https://peerlytics.xyz/skills/peerlytics.md>

## What it does

- sell USDC for fiat as a maker by creating non-custodial escrow deposits
- restrict a deposit to one approved buyer (OTC / private orders) and share a takeable link
- delegate rate management to the Delegate vault so integrators don't quote
- bridge USDC cross-chain via Circle CCTP (18+ chains) — UI surface only, not in the SDK
- supported payment rails: Venmo, Cashapp, Chime, Revolut, Wise, Zelle, PayPal, Monzo, N26

## Trust model

- non-custodial smart-contract escrow on Base — keys stay with the user
- no KYC at the app level — the SDK never sees identity docs
- payment verification uses the ZKP2P zero-knowledge proof + attestation flow
- makers control withdrawals at all times; deposits auto-close when filled (`retainOnEmpty=false`)
- bridge transfers go through Circle's CCTP contracts, not the SDK

## SDK surface (`@usdctofiat/offramp`)

- `offramp(walletClient, params)` — one-call sell flow (validate, approve, register, deposit, delegate). Supports `idempotencyKey` for 10-minute replay safety, `otcTaker` for private orders.
- `Offramp` class / `createOfframp(options)` — stateful variant with progress callbacks
- `deposits(address)`, `close(walletClient, depositId)`, `delegate(...)`, `undelegate(...)` — inventory + management queries
- `enableOtc`, `disableOtc`, `getOtcLink` — OTC whitelist hook + link helper
- `PLATFORMS`, `CURRENCIES` — canonical catalogs (zod-validated)
- `/react` entry: `useOfframp()`, `usePeerExtensionRegistration(platform)` hooks
- Re-exports: `peerExtensionSdk`, `getPeerExtensionState`, `openPeerExtensionInstallPage` for the PayPal + Wise handshake
- Errors: `OfframpError` with typed `code` — see `OFFRAMP_ERROR_CODES`

## Fees and constraints

- makers do not pay a platform fee on sells; the Delegate vault collects a 10 bps management fee on release
- every deposit delegates to the Delegate vault (business model — SDK enforces this)
- pricing is `track_market`; the vault oracle adjusts rates
- Base gas applies to all on-chain calls
- bridge transfers incur Circle CCTP fees

## Base contracts

- EscrowV2 (current): `0x777777779d229cdF3110e9de47943791c26300Ef`
- Legacy escrow (read-only network liquidity): `0x2f121CDDCA6d652f35e8B3E560f9760898888888`
- Orchestrator: `0x888888359E981B5225CA48fbCdCeff702FC3b888`
- USDC on Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Rate Manager Registry: `0xeed7db23e724ac4590d6db6f78fda6db203535f3`
- Delegate vault / rate manager ID: `0x8666d6fb0f6797c56e95339fd7ca82fdd348b9db200e10a4c4aa0a0b879fc41c`
- Bot wallet / referrer: `0xC141Cbe4f4a9CAbc3cc78159a9268a4e008922CD`
- Chain ID: `8453` (Base mainnet)

## Outbound webhooks

- Live events: `deposit.created`, `deposit.partially_filled`, `deposit.filled`, `deposit.closed`, `otc.taken`
- Reserved (not yet emitted): `otc.enabled`, `otc.disabled`
- Signed via `X-Usdctofiat-Signature: t=<unix>,v1=<hex>` (HMAC-SHA256 over `{timestamp}.{raw body}`, 5 min replay window)
- Headers: `X-Usdctofiat-Event`, `X-Usdctofiat-Delivery-Id`
- Dispatcher runs every ~60s; up to 5 retries with exponential backoff

## Ecosystem

- Peerlytics: <https://peerlytics.xyz> — analytics, explorer, paid API
- Delegate: <https://delegate.usdctofiat.xyz> — dashboard + marketing for the vault
- Peer Orderbook: <https://network.peerlytics.xyz> — public read-only orderbook
- ZKP2P protocol: <https://peer.xyz>
- peer-cli (agent CLI + MCP server): <https://agents.peer.xyz>

## For AI assistants

- Selling USDC for fiat → use `@usdctofiat/offramp`. Pass `idempotencyKey` for any server-side flow.
- Private / OTC deals → pass `otcTaker`; share the returned `otcLink`.
- PayPal or Wise → the user MUST complete the Peer extension handshake first. Catch `EXTENSION_REGISTRATION_REQUIRED` and drive `usePeerExtensionRegistration(platform)` or `peerExtensionSdk` directly.
- Market data, explorer, orderbook → use `@peerlytics/sdk` (combine with this skill for full integrations).
- Bridging cross-chain → this is a UI feature on usdctofiat.xyz, not part of the SDK.
- Always load `llms-full.txt` at session start for complete context.