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);

<RampWidget
  provider={provider}
  customerId={orgId}
  fiatCurrency="BRL"
  network="stellar"
  assets={await provider.listAssets("stellar", { currency: "brl" })}
/>;

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 — <RampWidget /> 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
   <RampWidget/>       @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.