# ramp-kit
**Category:** π¨βπ» Code Execution
**Repository:** https://github.com/armandocodecr/latam-ramp-kit
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/ramp-kit
## Description
LATAM fiat ramps on Stellar for AI agents: live quotes, sandbox orders, PIX/SPEI simulation, docs
## Claude Desktop Quick Installation
Heuristic fallback β verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"ramp-kit": {
"command": "npx",
"args": ["-y","ramp-kit"]
}
}
```
## Documentation & README
# LATAM Ramp Kit
[](https://www.npmjs.com/package/@ramp-kit/core)
[](https://www.npmjs.com/package/@ramp-kit/react)
[](https://www.npmjs.com/package/@ramp-kit/server)
[](https://www.npmjs.com/package/@ramp-kit/mcp)
[](https://registry.modelcontextprotocol.io/?search=io.github.armandocodecr/ramp-kit)
[](./LICENSE)
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
```bash
npm install @ramp-kit/core @ramp-kit/react # SDK + React widget
npm install @ramp-kit/server # production backend (optional)
```
For AI agents:
```bash
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.](https://stellar.expert/explorer/testnet/tx/95b4e01c139330fecfa9861d8a88735eec29433cdd5d6e7a67b2aaada98e00f4)
- **Out:** 5 USDC sold back to BRL β the provider pre-built the burn
transaction, the kit's `signAndSubmit` signed and submitted it
([burn tx](https://stellar.expert/explorer/testnet/tx/5bfc0470735be2a629870747e52edf429b3727d001f3721ee77a87f11f76cb6f)),
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 real ramp backends (plus a mock for instant dev):
| Provider | Rails | Networks | Role in the kit |
| --- | --- | --- | --- |
| [Etherfuse](https://docs.etherfuse.com) | **BRL (PIX)** + MXN (SPEI) | **Stellar** (native), Solana, Base, Polygon | Stellar-native settlement: automatic trustlines, sponsored onboarding via claimable balances |
| [Manteca](https://docs.manteca.dev/cripto) | **In:** BRL (PIX), ARS, MXN, CLP Β· **Out:** those + COP, PEN, GTQ, CRC, BOB, PUSD, PHP | **Stellar**, EVM chains, Tron | Broadest LATAM payout coverage β 11 countries β behind the same interface. **Verified live**: BRLβPIXβUSDC delivered on Stellar Testnet |
| `MockProvider` | any | Stellar | Instant local dev + integration tests, realistic order lifecycle |
```tsx
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:
```ts
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.
| | Etherfuse | Manteca | Kit exposes |
| --- | --- | --- | --- |
| Pricing | quote (2 min expiry) | price lock (`expireAt`) | `RampQuote.expiresAt` + auto-refresh |
| Execution | order | ramp synthetic (stages) | `RampOrder.status` (one lifecycle) |
| Deposit info | CLABE / PIX charge on order | `details.depositAddress` | `DepositInstructions` |
| Stellar | trustlines, claimable balances, tx expiry | β | `stellar.ts` helpers |
## Running the demo (100% sandbox, no real money)
```bash
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 β 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
```
```ts
// 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](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.
## 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](https://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`
3. 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 wallets compliant with no per-wallet KYC.
- PIX onramp orders report `depositBankName: "PIX"` with an empty CLABE β the
kit maps this to a PIX `DepositInstructions` automatically.
- First-time wallets receive tokens as **claimable balances** (plus ~1.5 XLM
sponsored reserves); `claimPendingBalances` builds trustline + claim in one
transaction.
## AI tooling: MCP server + agent skill
The kit ships first-class AI support β both for **understanding** it and for
**operating** it. An AI agent has already driven the full flow through these
tools: quoted 50 BRL β USDC, created the sandbox order, simulated the PIX
payment and watched it settle on Stellar Testnet.
- **[@ramp-kit/mcp](packages/mcp)** β MCP server published on
[npm](https://www.npmjs.com/package/@ramp-kit/mcp) and listed in the
[official MCP Registry](https://registry.modelcontextprotocol.io/?search=io.github.armandocodecr/ramp-kit)
as `io.github.armandocodecr/ramp-kit`. Nine tools: built-in documentation
(`get_documentation` with 6 topics), provider discovery, live quotes,
multi-provider comparison, sandbox orders, deposit simulation
(sandbox-only by design) and Stellar wallet inspection. Works
credential-free with the mock provider.
```bash
claude mcp add ramp-kit -e ETHERFUSE_API_KEY=api_sand_β¦ -- npx -y @ramp-kit/mcp
```
Or in any MCP client's `mcpServers` config:
```json
{ "ramp-kit": { "command": "npx", "args": ["-y", "@ramp-kit/mcp"] } }
```
- **[skills/ramp-kit](skills/ramp-kit)** β agent skill (Claude Code, Cursor,
and any agent supported by the [skills CLI](https://skills.sh)): teaches
the agent what the kit solves, the integration flow, sandbox setup,
verified troubleshooting and the production checklist.
```bash
npx skills add https://github.com/armandocodecr/latam-ramp-kit/tree/main/skills/ramp-kit
```
Together they cover both halves: the skill gives an agent the **knowledge**
to guide an integration; the MCP server gives it **hands** to actually
quote, order and verify against the sandbox. This pairs naturally with
Stellar's agentic-payments direction (x402/MPP): a ramp that AI agents can
understand and operate end-to-end.
## Path to production
The code is production-ready; what remains is provider onboarding. Ready today:
- **Environment switch** β `environment: "sandbox" | "production"` on every
provider flips base URLs; `stellarConfigFor("production")` returns mainnet
Horizon + network passphrase. No hardcoded issuers anywhere: assets are
always discovered via the provider, so mainnet identifiers flow through
automatically.
- **Server-side key handling** β `@ramp-kit/server` ships `createRampServer`:
the API key lives in your backend, the browser only reaches an allowlisted
ramp surface (quote/order/status), and the sandbox simulation endpoint is
hard-blocked in production.
- **Webhooks over polling** β `createEtherfuseWebhookHandler` verifies
`X-Signature` (HMAC-SHA256 over RFC 8785-canonicalized JSON, constant-time
compare), acks 2xx immediately, and dispatches typed events.
`verifyMantecaSignature` covers Manteca's shared-secret HMAC.
- **Real wallets** β signing is callback-based (`claimPendingBalances`,
`signAndSubmit`), so Freighter/hardware wallets plug in directly. The
demo's localStorage keypair is a sandbox convenience, not the pattern.
- **Sandbox-only code is fenced** β `simulateFiatReceived` throws in
production; deposits are detected from the real SPEI/PIX transfer.
External steps (with the provider, not in code):
1. **Etherfuse production KYB** β real legal-entity review (manual, allow
days/weeks), then an `api_prod_β¦` key. Register real bank accounts (real
CLABE/RFC) and confirm **BRL/PIX production availability** (live in
sandbox; listed as upcoming for production).
2. **End-user KYC** β production users complete the hosted identity flow
(documents + liveness); sandbox auto-approval does not apply.
3. **Manteca credentials** β commercial onboarding for a production
`md-api-key`, per-country permissions (BRL/PIX), and webhook secret;
confirm their signature header name during onboarding.
4. **Deploy `@ramp-kit/server`** behind HTTPS, register the webhook URL via
`POST /ramp/webhook`, and store the one-time secret.
5. **Persistence** β store quote/order idempotency UUIDs and webhook events
(dedupe by resource id + status) in your database.
## Repo layout
```
packages/core @ramp-kit/core β SDK, adapters, router, Stellar helpers
packages/react @ramp-kit/react β widget + hooks
packages/server @ramp-kit/server β production proxy + webhook verification
packages/mcp @ramp-kit/mcp β MCP server for AI agents (official MCP Registry)
api/ serverless ramp proxy for the deployed demo (Vercel)
skills/ramp-kit agent skill β integration knowledge for AI coding agents
examples/agent-checkout β third-party checkout using only the published npm artifacts
apps/demo primary demo (Etherfuse sandbox / mock, Stellar Testnet)
apps/second-app second integration of the same widget
docs/ provider research + Etherfuse OpenAPI spec
```