@ramp-kit/core - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

package.json

 {
   "name": "@ramp-kit/core",
-  "version": "0.1.0",
-  "description": "Unified on/off-ramp provider interface for LATAM (Etherfuse, Manteca) with Stellar-first support",
+  "version": "0.1.1",
+  "description": "Unified fiat on/off-ramp SDK for LATAM on Stellar: one provider interface over Etherfuse (PIX/SPEI, Stellar-native) and Manteca, with quote/order lifecycle normalization, multi-provider routing with live quote comparison, mock provider, and Stellar helpers (trustlines, claimable-balance claims, tx signing)",
   "type": "module",
@@ -6,0 +6,0 @@ "main": "./dist/index.js",

README.md

 # @ramp-kit/core
 
 Unified fiat on/off-ramp SDK for Latin America on Stellar. One `RampProvider`
-interface over Etherfuse (Stellar-native, PIX/SPEI) and Manteca (LATAM rails),
-plus a `MockProvider` for instant development, a country/currency router with
-live quote comparison, and Stellar helpers (trustlines, claimable-balance
-claims, transaction signing).
+interface over real ramp backends — write your integration once, swap
+providers with one line.
 
+Built for the Stellar "Brazil Ramps and Regional Kits" initiative and proven
+end-to-end on Stellar Testnet: BRL entered via PIX and settled as USDC in a
+fresh Stellar wallet, sponsored account creation included.
+
+## Why
+
+Every LATAM app that moves money between banks and blockchains hits the same
+wall: each ramp provider has its own API, auth scheme, KYC model, order states
+and price-expiry rules — and none covers the whole region. Integrating one
+takes weeks; integrating two doubles it. This SDK normalizes all of it behind
+a single interface.
+
+## Providers
+
+| Provider | Fiat rails | Settlement networks | Notes |
+| --- | --- | --- | --- |
+| `EtherfuseProvider` | BRL (PIX), MXN (SPEI) | **Stellar (native)**, Solana, Base, Polygon | Automatic trustlines, sponsored wallet onboarding via claimable balances, sandbox with full payment simulation |
+| `MantecaProvider` | BRL (PIX), ARS, MXN, CLP, COP, PEN… | EVM chains, Tron | Price locks + multi-stage synthetics, mapped to the same lifecycle |
+| `MockProvider` | BRL, MXN, ARS | Stellar | In-memory, realistic timing, optional auto-funding — for UI dev and tests |
+
+## Install
+
+```bash
+npm install @ramp-kit/core
+```
+
+## Quickstart (Etherfuse sandbox, no real money)
+
 ```ts
-import { EtherfuseProvider, stellarConfigFor } from "@ramp-kit/core";
+import { EtherfuseProvider } from "@ramp-kit/core";
 
-const provider = new EtherfuseProvider({ apiKey, environment: "sandbox" });
+const provider = new EtherfuseProvider({
+  apiKey: process.env.ETHERFUSE_API_KEY!, // api_sand_… from sandbox.etherfuse.com
+  environment: "sandbox",                 // "production" flips base URL
+});
+
+// 1. Pick the fiat leg and register the destination wallet (one time)
+const accounts = await provider.listBankAccounts();
+provider.setBankAccount(accounts.find((a) => a.compliant)!.bankAccountId);
+await provider.registerWallet(walletAddress, "stellar");
+
+// 2. Discover assets — identifiers are environment-specific, never hardcode
 const assets = await provider.listAssets("stellar", { currency: "brl" });
+const usdc = assets.find((a) => a.symbol === "USDC")!;
+
+// 3. Quote → order → deposit instructions
 const quote = await provider.getQuote({
   direction: "onramp",
   fiatCurrency: "BRL",
-  assetIdentifier: assets[0].identifier,
+  assetIdentifier: usdc.identifier,
   network: "stellar",
   sourceAmount: "100",
-  customerId,
+  customerId: orgId,
   walletAddress,
 });
 const order = await provider.createOrder(quote);
+console.log(order.depositInstructions); // { rail: "PIX", amount: "100", … }
+
+// 4. Sandbox only: simulate the incoming PIX/SPEI transfer
+await provider.simulateFiatReceived(order.id);
+
+// 5. Track to settlement
+const settled = await provider.getOrder(order.id); // status: "settled"
 ```
 
-Full documentation, demo apps and the React widget live in the
-[latam-ramp-kit repository](https://github.com/armandocodecr/latam-ramp-kit).
+## Normalized order lifecycle
+
+Every provider's states map to one lifecycle your UI can rely on:
+
+```
+created → awaiting_deposit → awaiting_signature? → processing → settled
+                                                              ↘ failed | cancelled
+```
+
+Quotes always carry `expiresAt` (Etherfuse: 2 min; Manteca price locks:
+asset-dependent) so UIs can refresh proactively — or use `useQuote` from
+[@ramp-kit/react](https://www.npmjs.com/package/@ramp-kit/react) which does it
+automatically.
+
+## Multi-provider routing
+
+```ts
+import { RampRouter } from "@ramp-kit/core";
+
+const router = new RampRouter()
+  .register(new EtherfuseProvider({ apiKey }))
+  .register(new MantecaProvider({ apiKey: mantecaKey }));
+
+// Best provider for the corridor (Stellar-native preferred)
+const provider = router.resolve({ country: "BR", fiatCurrency: "BRL" });
+
+// Or fan out and compare live quotes across all eligible providers
+const quotes = await router.compareQuotes(request, { fiatCurrency: "BRL" });
+```
+
+## Stellar helpers
+
+Sponsored onramps deliver tokens as claimable balances when the wallet lacks
+a trustline (or doesn't exist yet). The helpers close that loop:
+
+```ts
+import {
+  getAccountState,      // exists? trustline? XLM reserves?
+  getPendingBalances,   // claimable balances waiting for the wallet
+  claimPendingBalances, // trustline(s) + claim in ONE tx, callback signing
+  signAndSubmit,        // submit provider-built txs, detects tx_too_late
+  stellarConfigFor,     // "sandbox" → Testnet, "production" → mainnet
+} from "@ramp-kit/core";
+
+await claimPendingBalances(walletAddress, async (xdr, passphrase) => {
+  // plug in Freighter, a hardware wallet, or any signer
+  return await freighter.signTransaction(xdr, { networkPassphrase: passphrase });
+}, stellarConfigFor("sandbox"));
+```
+
+Signing is always callback-based — secret keys never touch the SDK.
+
+## Error handling
+
+All failures throw `RampError` with the provider name preserved and a typed
+`code`: `auth`, `quote_expired`, `tx_expired`, `kyc_required`, `unsupported`,
+`network`, `provider_error`.
+
+## Production
+
+Provider API keys are server-side secrets: pair this SDK with
+[@ramp-kit/server](https://www.npmjs.com/package/@ramp-kit/server) (allowlisted
+proxy + webhook signature verification). Full path-to-production checklist in
+the [repository](https://github.com/armandocodecr/latam-ramp-kit#path-to-production).
+
+## Related packages
+
+- [@ramp-kit/react](https://www.npmjs.com/package/@ramp-kit/react) — embeddable `<RampWidget />` + hooks
+- [@ramp-kit/server](https://www.npmjs.com/package/@ramp-kit/server) — production proxy + webhooks
+
+MIT © [Armando Cruz](https://github.com/armandocodecr) ·
+[Repository & demo apps](https://github.com/armandocodecr/latam-ramp-kit)

No alert changes

Improved metrics

Total package byte prevSize

109430

4.54%

Number of lines in readme file

144

414.29%

No dependency changes