@ramp-kit/react

Drop-in React UI for LATAM fiat on/off-ramps on Stellar. Embeds a complete onramp flow — live quote with countdown, PIX/SPEI deposit instructions, order tracking to settlement — on top of any @ramp-kit/core provider (Etherfuse, Manteca, or the built-in mock).

Install

npm install @ramp-kit/core @ramp-kit/react

React ≥ 18 is a peer dependency.

<RampWidget />

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

const provider = new EtherfuseProvider({ apiKey, environment: "sandbox" });

<RampWidget
  provider={provider}
  customerId={orgId}
  fiatCurrency="BRL"
  network="stellar"
  walletAddress={userWallet}
  assets={await provider.listAssets("stellar", { currency: "brl" })}
  onOrderCreated={(id) => console.log("order", id)}
  onSettled={(id) => console.log("funds delivered", id)}
/>;

The widget walks the user through a 3-step flow:

1. Amount — amount + asset selection, live quote with expiry countdown that re-quotes automatically when the provider's price expires.
2. Deposit — rail-aware instructions (PIX charge vs. SPEI CLABE) with a live status indicator polled until terminal state.
3. Done — conversion summary and on-chain transaction hash.

Props

| Prop | Type | Description | | --- | --- | --- | | provider | RampProvider | Any @ramp-kit/core provider instance | | customerId | string | Provider-side customer id (org UUID for Etherfuse, userAnyId for Manteca) | | fiatCurrency | "BRL" \| "MXN" \| … | Fiat leg of the ramp | | direction | "onramp" \| "offramp" | Buy (default) or sell flow | | network | Network | Settlement network (default "stellar") | | walletAddress | string? | Destination wallet (onramp) / source wallet (offramp) | | assets | RampAsset[] | Assets to offer (from provider.listAssets()) | | signer | (xdr, passphrase) => Promise<string> | Wallet signing callback for offramps (Freighter, hardware, local key) | | stellarConfig | StellarConfig | Network for signing — stellarConfigFor("sandbox" \| "production") | | onOrderCreated | (orderId) => void | Fired when the order is accepted | | onSettled | (orderId) => void | Fired when funds are delivered |

Sell flow (offramp) with Freighter

import { signTransaction } from "@stellar/freighter-api";
import { stellarConfigFor } from "@ramp-kit/core";

<RampWidget
  provider={provider}
  customerId={orgId}
  direction="offramp"
  fiatCurrency="BRL"
  walletAddress={userAddress}
  assets={assets}
  signer={async (xdr, networkPassphrase) => {
    const res = await signTransaction(xdr, { networkPassphrase, address: userAddress });
    return res.signedTxXdr;
  }}
  stellarConfig={stellarConfigFor("sandbox")}
/>;

The widget renders an in-widget "Sign & send" step, recovers automatically from expired provider transactions (tx_too_late → regenerate → re-sign), and links the settlement transaction on Stellar Expert.

Styling: neutral inline styles plus rk- class names (rk-widget, rk-quote, rk-deposit, rk-done) so you can theme it from your own CSS.

Hooks (build your own UI)

import { useQuote, useOrder } from "@ramp-kit/react";

// Live quote that refreshes itself when it expires
const { quote, loading, error, secondsLeft, refresh } = useQuote(provider, {
  direction: "onramp",
  fiatCurrency: "BRL",
  assetIdentifier: usdc.identifier,
  network: "stellar",
  sourceAmount: "100",
  customerId,
});

// Order polling that stops at settled/failed/cancelled
const { order, polling } = useOrder(provider, orderId);

Instant development with the mock provider

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

// Realistic lifecycle without credentials; auto-funds orders after 4s
const provider = new MockProvider({ autoFundMs: 4000 });

Two demo apps (a full sandbox demo on Stellar Testnet and a second minimal integration) live in the latam-ramp-kit repository.

AI tooling

Building this integration with an AI coding agent? Install the kit's agent skill (npx skills add https://github.com/armandocodecr/latam-ramp-kit/tree/main/skills/ramp-kit) and the @ramp-kit/mcp MCP server — the agent gets integration knowledge, verified troubleshooting, and live tools to quote and test orders against the sandbox.

MIT © Armando Cruz