@usdctofiat/offramp 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# @usdctofiat/offramp
+
+USDC-to-fiat offramp SDK for Base. Create and manage delegated deposits in one function call.
+
+## Install
+
+```bash
+npm install @usdctofiat/offramp
+```
+
+## Quick Start
+
+```typescript
+import { Offramp } from "@usdctofiat/offramp";
+
+const offramp = new Offramp();
+
+const result = await offramp.createDeposit(walletClient, {
+  amount: "100",
+  platform: "revolut",
+  currency: "EUR",
+  identifier: "alice",
+});
+
+console.log(result.depositId, result.txHash);
+```
+
+## Deposit Management
+
+```typescript
+// List deposits
+const deposits = await offramp.getDeposits("0xYourAddress");
+// [{ depositId, status, remainingUsdc, fulfilledIntents, delegated, ... }]
+
+// Close and withdraw
+const txHash = await offramp.withdrawDeposit(walletClient, "123");
+```
+
+## React
+
+```typescript
+import { useOfframp } from "@usdctofiat/offramp/react";
+
+function SellButton({ walletClient }) {
+  const { createDeposit, step, isLoading, error, getDeposits } = useOfframp();
+
+  return (
+    <button
+      disabled={isLoading}
+      onClick={() =>
+        createDeposit(walletClient, {
+          amount: "100",
+          platform: "revolut",
+          currency: "EUR",
+          identifier: "alice",
+        })
+      }
+    >
+      {step ?? "Sell USDC"}
+    </button>
+  );
+}
+```
+
+## Progress Callbacks
+
+```typescript
+await offramp.createDeposit(walletClient, params, (progress) => {
+  // progress.step: "approving" | "registering" | "depositing" | "confirming" | "delegating" | "done"
+  // progress.txHash: available after "depositing"
+  // progress.depositId: available after "confirming"
+});
+```
+
+## Discovery & Validation
+
+```typescript
+offramp.getPlatforms();
+// [{ id: "revolut", name: "Revolut", currencies: [...], identifierLabel, identifierPlaceholder, helperText }]
+
+offramp.getCurrencies("wise");
+// ["USD", "EUR", "GBP", "AUD", ...]
+
+offramp.validateIdentifier("revolut", "@alice");
+// { valid: true, normalized: "alice" }
+```
+
+## Supported Platforms
+
+| Platform | Currencies | Identifier |
+|----------|-----------|-----------|
+| Revolut | 23 currencies | Revtag |
+| Wise | 30+ currencies | Wisetag |
+| PayPal | 7 currencies | Email |
+| Venmo | USD | Username |
+| Cash App | USD | Cashtag |
+| Zelle | USD | Email |
+| Monzo | GBP | Username |
+| N26 | EUR | IBAN |
+| Chime | USD | ChimeSign |
+| Mercado Pago | ARS | CVU |
+
+## Error Handling
+
+```typescript
+import { OfframpError } from "@usdctofiat/offramp";
+
+try {
+  await offramp.createDeposit(walletClient, params);
+} catch (err) {
+  if (err instanceof OfframpError) {
+    console.log(err.code);      // "VALIDATION" | "USER_CANCELLED" | "DEPOSIT_FAILED" | ...
+    console.log(err.step);      // Which step failed
+    console.log(err.txHash);    // Available if deposit was created on-chain
+    console.log(err.depositId); // Available if deposit was confirmed but delegation failed
+  }
+}
+```
+
+## How It Works
+
+Every deposit created through this SDK is automatically:
+
+1. **Delegated** to the USDCtoFiat Delegate vault for rate management
+2. **Market-tracking** via oracle-based pricing
+3. **Auto-closing** when fully filled
+4. **Attributed** to Galleon Labs via ERC-8021
+
+## Requirements
+
+- Base network (chain ID 8453)
+- viem `WalletClient` with an account
+- USDC balance on Base