ramp-kit

LATAM Ramp Kit

即插即用的 SDK + React 组件，可为拉丁美洲的任何应用添加法币出入金功能， 专为 Stellar 巴西出入金和区域工具包子赛道打造。

安装

npm install @ramp-kit/core @ramp-kit/react   # SDK + React widget
npm install @ramp-kit/server                 # production backend (optional)

面向 AI Agent：

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

在 Stellar Testnet（Etherfuse 沙盒）上验证过的 BRL 入金和出金流程：

• **入金：**通过 PIX 存入 100 BRL，并以 19.0097 USDC 结算到一个新建的 Stellar 钱包——由服务提供方赞助创建账户，通过可领取余额交付代币， 再用工具包中的一个辅助函数领取。 Stellar Expert 上的结算交易。
• **出金：**将 5 USDC 卖回 BRL——服务提供方预先构建了销毁交易，工具包的 signAndSubmit 对其签名并提交 （销毁交易）， PIX 付款由服务提供方处理。该组件提供完整的卖出流程，支持组件内签名和自动 tx_too_late 恢复。

一个服务提供方接口、两个直连后端，以及任何兼容 SEP 的 Stellar 锚点 （另有用于快速开发的模拟服务提供方）：

服务提供方	支付渠道	网络	在工具包中的角色
Etherfuse	BRL（PIX） + MXN（SPEI）	Stellar（原生）、Solana、Base、Polygon	Stellar 原生结算：自动建立信任线，通过可领取余额赞助用户入驻
Manteca	**入金：**BRL（PIX）、ARS、MXN、CLP · **出金：**上述币种 + COP、PEN、GTQ、CRC、BOB、PUSD、PHP	Stellar、EVM 链、Tron	通过同一接口覆盖最广的 LATAM 出金渠道——11 个国家。已验证线上流程：在 Stellar Testnet 上完成 BRL→PIX→USDC 交付
SepProvider	锚点支持的任意渠道	Stellar	对接任何兼容 SEP 的锚点（SEP-1/10/38/24）：最终用户使用自己的钱包进行身份验证，无需合作方密钥。一个适配器，覆盖整个锚点生态
MockProvider	任意	Stellar	快速本地开发和集成测试，支持逼真的订单生命周期

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" })}
/>;

切换服务提供方只需一行代码（new MantecaProvider({ apiKey })、 new MockProvider()）；也可以让路由器按国家选择服务提供方并比较实时报价：

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

包

• @ramp-kit/core — 与框架无关的 TypeScript SDK
  • RampProvider 接口：listAssets → getQuote → createOrder → getOrder
  • 规范化的订单生命周期：created → awaiting_deposit → awaiting_signature → processing → settled | failed | cancelled
  • EtherfuseProvider（包括 registerWallet、listBankAccounts、沙盒环境中的 simulateFiatReceived）、MantecaProvider、MockProvider
  • RampRouter：按国家／货币选择服务商，并比较实时报价
  • Stellar 辅助函数：getAccountState（检查信任线／储备金）、getPendingBalances / claimPendingBalances（赞助式入金申请）、signAndSubmit（处理 tx_too_late → 重新生成）、parseAssetIdentifier
• @ramp-kit/react — 可嵌入的 <RampWidget /> 分步流程（实时报价倒计时、PIX/SPEI 入金说明、状态跟踪）、useQuote（过期后自动刷新）、useOrder（轮询直至终止状态）
• @ramp-kit/server — 零依赖生产后端：带严格端点允许列表的 API 密钥代理，以及通过 HMAC-SHA256 签名验证的 webhook 接收器（Etherfuse 使用 RFC 8785 规范化）
• apps/demo — 在 Stellar Testnet 上运行的完整 BRL·PIX / MXN·SPEI 入金流程：内置测试钱包、实时 Horizon 余额面板、一键申请
• apps/second-app — 将同一组件嵌入另一个应用（子赛道的“在第二个应用中正常运行”标准）

为什么要使用两个服务商

Manteca 提供覆盖面最广的 LATAM 法币通道；Etherfuse 则基于 Stellar，并支持赞助式钱包接入。两者都在 Stellar 上结算 USDC（Manteca 最近新增了 Stellar 支持——本工具包已通过实时验证），因此可以在同一通道上进行真正的多锚点比较： RampRouter.compareQuotes 会将一个请求发送给两者，并按汇率排序后返回实时结果（已验证：100 BRL → Etherfuse 的 19.49 USDC，相比 Manteca 的 19.23 USDC）。 它们仍采用截然不同的思路（报价／订单 vs. 多阶段合成资产 + 价格锁定）——工具包通过统一接口屏蔽了这些差异，而这正是应用在该地区集成入金服务时首先遇到的难题。

	Etherfuse	Manteca	工具包提供
定价	报价（2 min 有效期）	价格锁定（expireAt）	RampQuote.expiresAt + 自动刷新
执行	订单	入金合成资产（分阶段）	RampOrder.status（统一生命周期）
入金信息	订单上的 CLABE / PIX 付款请求	details.depositAddress	DepositInstructions
Stellar	信任线、可领取余额、交易过期	—	stellar.ts 辅助函数

运行演示（100% 沙盒环境，无真实资金）

pnpm install
pnpm dev        # demo on http://localhost:5173

零配置路径： 选择“Mock provider”，即可立即体验完整流程。

真实沙盒路径（Stellar Testnet）：

1. 在 https://sandbox.etherfuse.com 创建沙盒账户 — 使用沙盒按钮批准自己的 KYB。
2. 在控制面板中，使用 Add BRL Bank Account (PIX) — 此账户已预填测试值，可立即使用。（通过 API 注册的 MXN 账户需等待异步审批。）
3. 将 api_sand… 密钥复制到演示中，并连接 Freighter（所有操作均由你自己的钱包签名 — 或生成一个临时测试钱包；提供商注册会自动完成）。运行入金流程：报价 → 订单 → 模拟 PIX 入账 → 等待资金在 Stellar Testnet 上结算 → 一键领取到账的可领取余额。然后切换到卖出，反向操作：USDC → BRL，在钱包中签名，并将两笔交易链接到 Stellar Expert 以供公开验证。

Manteca 沙盒（https://sandbox.manteca.dev/crypto/v2）需要 Manteca 团队提供凭据；此适配器根据其公开文档实现，并提供相同的标准化生命周期。

关于 API 密钥的说明： 提供商密钥用于标识你的企业（其 KYB、费用和结算账户）— 每个应用有一个密钥，由服务器端保管，终端用户永远不会看到。用户是该企业的客户，通过 customerId 进行标识。演示要求你粘贴密钥，只是因为打开演示的人扮演的是集成开发者。

将其部署给你自己的用户

你只需从 Etherfuse 和/或 Manteca 获取一次合作伙伴密钥。用户只需点击购买 — 他们永远不会看到密钥或 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" });

可在 examples/backend-integration 运行 — 已使用空客户端密钥，在真实沙盒中完成端到端验证：报价 → 订单 → 存款 → settled；而特权端点（用户注册、公司配置、会计）通过代理访问时会返回 403。

唯一需要你负责的部分：为每位用户向提供商办理注册（KYC），以获取其 customerId。这是运营法币出入金服务的必要环节 — 从报价开始，工具包会处理其余流程。

为什么需要后端？ 前端环境变量（VITE_*、NEXT_PUBLIC_*）会嵌入到所提供的 JS 包中 — 任何访客都能读取，因此其中的合作伙伴密钥会暴露。密钥必须存放在后端环境变量中，并由 @ramp-kit/server 提供保护（这是一个约 10 行代码的无服务器函数，而非真正的基础设施）。例外是 SEP-anchor 路由：SepProvider 不需要合作伙伴密钥 — 终端用户使用自己的钱包进行身份验证 — 因此它完全运行在前端。

skills/ramp-kit/references/environments.md 提供了测试网和主网的完整分步指南（环境文件、唯一的 RAMP_ENV 标志、钱包网络、凭据检查清单）。同一指南也包含在 AI 工具中 — 使用此工具包技能或 @ramp-kit/mcp 服务（get_documentation → environments）的 Agent 可以引导你完成设置。

部署演示（Vercel）

演示项目已准备就绪，可直接部署——在仓库根目录下有一个无服务器代理 api/[...path].ts （Vercel 会自动检测到）：

1. 前往 vercel.com/new → 导入 armandocodecr/latam-ramp-kit。
2. 根目录： ./ · 框架预设： Other，并在 Build & Development Settings 中设置以下三项覆盖：
   • Install Command: pnpm install
   • Build Command: pnpm -r build
   • Output Directory: apps/demo/dist
3. 部署。无需环境变量。

部署后的演示项目功能：

• 模拟提供方对所有人开放，无需任何设置——支持完整的组件流程，包括买入和卖出。
• 实时沙盒模式会转发访客自己的密钥：浏览器调用 /api/<provider>/*，该函数会将请求转发给提供方，并使用与 @ramp-kit/server 强制执行的相同端点允许列表。部署不会持有任何凭据，也不会存储任何内容。
• 上游服务固定使用提供方的沙盒主机，因此已部署的演示项目绝不会触及真实资金。

实测记录（经真实沙盒验证）

• GET /ramp/assets 需要 blockchain、currency 和 wallet——该工具包会填入合理的默认值。
• 自带的钱包必须先注册，才能创建首笔订单——SDK 会自动修复此问题：createOrder 会注册钱包（幂等操作），并在遇到 "Wallet not found" 时重试。经 KYB 审核通过的组织设置 claimOwnership: true 后，可将钱包标记为合规，无需对每个钱包单独进行 KYC。
• PIX 入金订单会返回 depositBankName: "PIX"，且 CLABE 为空——该工具包会自动将其映射为 PIX DepositInstructions。
• 首次使用的钱包会收到可领取余额（以及约 1.5 XLM 的赞助储备金）；claimPendingBalances 会在一笔交易中构建信任线并领取余额。

AI 工具：MCP 服务 + Agent 技能

该工具包提供一流的 AI 支持，既能帮助 AI 理解它，也能让 AI 操作它。AI Agent 已通过这些工具驱动完整流程：对 50 BRL → USDC 进行报价、创建沙盒订单、模拟 PIX 付款，并在 Stellar Testnet 上确认结算。

• @ramp-kit/mcp — MCP 服务，已发布到 npm，并列入 官方 MCP Registry， 名称为 io.github.armandocodecr/ramp-kit。提供九种工具：内置文档 （get_documentation，包含 6 个主题）、提供方发现、实时报价、 多提供方比较、沙盒订单、入金模拟（按设计仅支持沙盒）和 Stellar 钱包检查。使用模拟提供方时无需凭据。

  claude mcp add ramp-kit -e ETHERFUSE_API_KEY=api_sand_… -- npx -y @ramp-kit/mcp
  

  或在任何 MCP 客户端的 mcpServers 配置中：

  { "ramp-kit": { "command": "npx", "args": ["-y", "@ramp-kit/mcp"] } }
  

• skills/ramp-kit — Agent 技能（适用于 Claude Code、Cursor， 以及 skills CLI 支持的任何 Agent）：向 Agent 介绍该工具包解决的问题、集成流程、沙盒设置、 经验证的故障排查方法和生产环境检查清单。

  npx skills add https://github.com/armandocodecr/latam-ramp-kit/tree/main/skills/ramp-kit
  

两者结合，覆盖了两个方面：技能让 Agent 拥有指导集成所需的知识；MCP 服务则赋予它实际进行报价、下单和针对沙盒验证的能力。这与 Stellar 的 Agent 式支付方向（x402/MPP）相得益彰：让 AI Agent 能够端到端理解和操作的 ramp。

迈向生产环境

代码已可用于生产环境；剩下的工作是接入服务提供商。当前已就绪：

• 环境切换 — 每个服务提供商都可通过 environment: "sandbox" | "production" 切换基础 URL；stellarConfigFor("production") 会返回主网 Horizon 和网络密码短语。代码中没有硬编码的发行方：资产始终通过服务提供商发现，因此主网标识符会自动传递。
• 服务端密钥处理 — @ramp-kit/server 提供 createRampServer：API 密钥保存在后端，浏览器只能访问允许列表中的 Ramp 接口（报价/订单/状态），并且沙盒模拟端点在生产环境中会被完全禁用。
• 使用 Webhook 而非轮询 — createEtherfuseWebhookHandler 会验证 X-Signature（对 RFC 8785 规范化 JSON 进行 HMAC-SHA256 计算，并以恒定时间进行比较），立即返回 2xx 确认，并分发类型化事件。verifyMantecaSignature 可验证 Manteca 的共享密钥 HMAC。
• 真实钱包 — 签名基于回调（claimPendingBalances、signAndSubmit），因此可直接接入 Freighter/硬件钱包。演示中的 localStorage 密钥对只是沙盒便利功能，并非推荐模式。
• 沙盒专用代码已隔离 — simulateFiatReceived 在生产环境中会抛出错误；存款会通过真实的 SPEI/PIX 转账进行检测。

外部步骤（通过服务提供商完成，而非在代码中完成）：

1. Etherfuse 生产环境 KYB — 完成真实的法人实体审核（人工审核，可能需要数天或数周），之后获取一个 api_prod_… 密钥。注册真实银行账户（真实 CLABE/RFC），并确认 BRL/PIX 生产环境可用性（沙盒中已上线；生产环境中列为即将推出）。
2. 最终用户 KYC — 生产环境中的用户需完成托管式身份验证流程（证件 + 活体检测）；沙盒中的自动批准不适用。
3. Manteca 凭据 — 商务接入生产环境，获取 md-api-key、各国家/地区权限（BRL/PIX）和 Webhook 密钥；接入期间确认其签名请求头名称。
4. 通过 HTTPS 部署 @ramp-kit/server，通过 POST /ramp/webhook 注册 Webhook URL，并保存一次性密钥。
5. 持久化 — 在数据库中保存报价/订单幂等 UUID 和 Webhook 事件（按资源 ID + 状态去重）。

仓库布局

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