Ramp Kit

LATAM Ramp Kit

Drop-in SDK + React components to add fiat on/off-ramps to any app in Latin America, built for the Stellar Brazil Ramps and Regional Kits sub-lane.

Install

npm install @ramp-kit/core @ramp-kit/react   # SDK + React widget

npm install @ramp-kit/server # production backend (optional)

For AI agents:

claude mcp add ramp-kit -- npx -y @ramp-kit/mcp                                          # MCP server

npx skills add https://github.com/armandocodecr/latam-ramp-kit/tree/main/skills/ramp-kit # agent skill

**BRL in *and* out, proven on Stellar Testnet (Etherfuse sandbox):**

• In: 100 BRL entered via PIX and settled as 19.0097 USDC in a fresh Stellar wallet — account creation sponsored by the provider, tokens delivered via claimable balance, claimed with one kit helper. Settlement tx on Stellar Expert.
• Out: 5 USDC sold back to BRL — the provider pre-built the burn transaction, the kit's signAndSubmit signed and submitted it (burn tx), and the PIX payout processed provider-side. The widget ships the full Sell flow with in-widget signing and automatic tx_too_late recovery.

One provider interface, two direct backends plus any SEP-compliant Stellar anchor (and a mock for instant dev):

import { EtherfuseProvider } from "@ramp-kit/core";

import { RampWidget } from "@ramp-kit/react";

const provider = new EtherfuseProvider({ apiKey }); provider.setBankAccount((await provider.listBankAccounts())[0].bankAccountId);

;

Swapping providers is one line (new MantecaProvider({ apiKey }), new MockProvider()), or let the router pick per country and compare live quotes:

const router = new RampRouter()

.register(new EtherfuseProvider({ apiKey })) .register(new MantecaProvider({ apiKey: mantecaKey }));

// Routing is direction-aware: Manteca pays out across 11 countries but only // takes deposits in 4, so the same corridor can resolve differently. const provider = router.resolve({ country: "CO", fiatCurrency: "COP", direction: "offramp", }); const quotes = await router.compareQuotes(request, { fiatCurrency: "BRL" });

Packages

• `@ramp-kit/core` — framework-agnostic TypeScript SDK
• RampProvider interface: listAssets → getQuote → createOrder → getOrder
• Normalized order lifecycle: created → awaiting_deposit → awaiting_signature → processing → settled | failed | cancelled
• EtherfuseProvider (incl. registerWallet, listBankAccounts, sandbox simulateFiatReceived), MantecaProvider, MockProvider
• RampRouter: provider selection per country/currency + live quote comparison
• Stellar helpers: getAccountState (trustline/reserve checks), getPendingBalances / claimPendingBalances (sponsored-onramp claims), signAndSubmit (handles tx_too_late → regenerate), parseAssetIdentifier
• `@ramp-kit/react` — embeddable stepper flow (live quote countdown, PIX/SPEI deposit instructions, status tracking), useQuote (auto-refresh on expiry), useOrder (polls until terminal state)
• `@ramp-kit/server` — zero-dependency production backend: API-key proxy with a strict endpoint allowlist, plus webhook receivers with HMAC-SHA256 signature verification (RFC 8785 canonicalization for Etherfuse)
• `apps/demo` — full BRL·PIX / MXN·SPEI onramp on Stellar Testnet: built-in test wallet, live Horizon balance panel, one-click claim
• `apps/second-app` — the same widget dropped into a different app (the sub-lane's "works in a second app" criterion)

Why two providers

Manteca has the broadest LATAM fiat rails; Etherfuse is Stellar-native with sponsored wallet onboarding. Both settle USDC on Stellar (Manteca added Stellar support recently — verified live by this kit), which makes real multi-anchor comparison possible on the same corridor: RampRouter.compareQuotes fans one request out to both and returns live rates sorted (verified: 100 BRL → 19.49 USDC Etherfuse vs 19.23 USDC Manteca). They still expose completely different mental models (quote/order vs. multi-stage synthetics + price locks) — the kit hides that behind one interface, which is exactly the pain an app integrating ramps in the region hits first.

Running the demo (100% sandbox, no real money)

pnpm install

pnpm dev # demo on http://localhost:5173

Zero-setup path: pick "Mock provider" and walk the full flow immediately.

Real sandbox path (Stellar Testnet):

1. Create a sandbox account at https://sandbox.etherfuse.com — approve your own KYB with the sandbox button.
2. In the dashboard, use Add BRL Bank Account (PIX) — it comes pre-filled with test values and is compliant instantly. (MXN accounts registered via API await async approval.)
3. Copy your api_sand… key into the demo and connect Freighter (your own wallet signs everything — or generate a throwaway test wallet; the provider registration happens automatically). Run an onramp: quote → order → simulate the incoming PIX → watch it settle on Stellar Testnet → claim the delivered claimable balance with one click. Then flip to Sell to go the other way: USDC → BRL with in-wallet signing, both transactions linked to Stellar Expert for public verification.

Manteca sandbox (https://sandbox.manteca.dev/crypto/v2) requires credentials from the Manteca team; the adapter is implemented from their public docs and ships with the same normalized lifecycle.

Note on API keys: a provider key identifies your *business* (its KYB,

fees and settlement accounts) — there is one per app, held server-side, and

end users never see it. They are customers under it, identified by

customerId. The demo asks you to paste a key only because whoever opens

it is playing the role of the integrating developer.

Shipping it to your own users

You get partner keys from Etherfuse and/or Manteca once. Your users just click buy — they never see a key or an API.

browser (no key)  →  your backend (keys in env)  →  Etherfuse / Manteca

@ramp-kit/server

// your backend — the only place keys exist

createRampServer({ proxy: { apiKey: process.env.ETHERFUSE_API_KEY!, environment: "production" }, manteca: { apiKey: process.env.MANTECA_API_KEY!, environment: "production" }, }).listen(8787);

// your frontend — empty key, pointed at your backend new EtherfuseProvider({ apiKey: "", baseUrl: "https://api.myapp.com/ramp/etherfuse" });

Runnable in examples/backend-integration — verified end to end against the real sandboxes with an empty client key: quote → order → deposit → settled, while privileged endpoints (user onboarding, company config, accounting) return 403 through the proxy.

The one piece that stays yours: onboarding each user with the provider (KYC) to get their customerId. That's inherent to operating a ramp — from quote onward the kit handles it.

Why a backend at all? Frontend env vars (VITE_*, NEXT_PUBLIC_*) are embedded in the served JS bundle — any visitor can read them, so a partner key there is exposed. The key must live in a backend env var behind @ramp-kit/server (a ~10-line serverless function, not real infrastructure). The exception is the SEP-anchor route: SepProvider needs no partner key — the end user authenticates with their own wallet — so it runs entirely in the frontend.

Full step-by-step for testnet and mainnet (env files, the single RAMP_ENV flag, wallet networks, credential checklists): skills/ramp-kit/references/environments.md. The same guide ships inside the AI tooling — agents with the kit's skill or the @ramp-kit/mcp server (get_documentation → environments) can walk you through it.

Deploy the demo (Vercel)

The demo ships ready to deploy — a serverless proxy at api/[...path].ts (auto-detected by Vercel at the repo root):

1. vercel.com/new → import armandocodecr/latam-ramp-kit.
2. Root Directory: ./ · Framework Preset: Other, with three overrides in Build & Development Settings:

• Install Command: pnpm install
• Build Command: pnpm -r build
• Output Directory: apps/demo/dist

1. Deploy. No environment variables are needed.

What the deployed demo does:

• Mock provider works for everyone, with zero setup — the full widget flow, buy and sell.
• Live sandbox modes relay the visitor's own key: the browser calls /api/ /*, the function forwards it to the provider with the same endpoint allowlist @ramp-kit/server enforces. The deployment holds no credentials and stores nothing.
• Upstreams are pinned to the providers' sandbox hosts, so a deployed demo can never reach production money.

Field notes (verified against the real sandbox)

• GET /ramp/assets requires blockchain, currency and wallet — the kit fills sensible defaults.
• Bring-your-own wallets must be registered before their first order — the SDK self-heals this: createOrder registers (idempotent) and retries on "Wallet not found". claimOwnership: true under a KYB-approved org marks wal