@ramp-kit/core

@ramp-kit/core

Unified fiat on/off-ramp SDK for Latin America on Stellar. One RampProvider 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

npm install @ramp-kit/core

Quickstart (Etherfuse sandbox, no real money)

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

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: usdc.identifier,
  network: "stellar",
  sourceAmount: "100",
  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"

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 which does it automatically.

Multi-provider routing

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:

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 (allowlisted proxy + webhook signature verification). Full path-to-production checklist in the repository.

AI tooling

• @ramp-kit/mcp — MCP server (listed in the official MCP Registry) so AI agents can quote, create sandbox orders and inspect wallets: claude mcp add ramp-kit -- npx -y @ramp-kit/mcp
• Agent skill with integration knowledge and verified troubleshooting: npx skills add https://github.com/armandocodecr/latam-ramp-kit/tree/main/skills/ramp-kit

Related packages

• @ramp-kit/react — embeddable <RampWidget /> + hooks
• @ramp-kit/server — production proxy + webhooks
• @ramp-kit/mcp — MCP server for AI agents

MIT © Armando Cruz · Repository & demo apps