@ramp-kit/react

@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:

• Amount — amount + asset selection, live quote with expiry countdown that re-quotes automatically when the provider's price expires.
• Deposit — rail-aware instructions (PIX charge vs. SPEI CLABE) with a live status indicator polled until terminal state.
• 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