ramp-kit

LATAM Ramp Kit

ラテンアメリカのあらゆるアプリに法定通貨のオン／オフランプを追加できる、すぐに導入可能な SDK と React コンポーネントです。Stellar の Brazil Ramps and Regional Kits サブレーン向けに構築されています。

インストール

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

AI エージェント向け：

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 が、新規 Stellar ウォレットで 19.0097 USDC として決済されます。アカウント作成はプロバイダーがスポンサーし、トークンは請求可能残高を通じて送付され、キットのヘルパーを 1 つ使って請求できます。 Stellar Expert で決済トランザクションを確認。
• 出金： 5 USDC を BRL に売却します。プロバイダーがバーン用のトランザクションを事前に構築し、キットの signAndSubmit が署名して送信します（バーントランザクション）。PIX での支払い処理はプロバイダー側で行われます。ウィジェットには、ウィジェット内署名と tx_too_late の自動リカバリーを備えた売却フロー全体が含まれています。

1 つのプロバイダーインターフェース、2 つの直接バックエンドに加え、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 か国。ライブ環境で検証済み：BRL→PIX→USDC が Stellar Testnet で送付されました
SepProvider	アンカーが対応するあらゆる決済レール	Stellar	SEP 準拠のあらゆるアンカー（SEP-1/10/38/24）に対応します。エンドユーザーは自身のウォレットで認証するため、パートナーキーは不要です。1 つのアダプターでアンカーエコシステム全体を利用できます
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" })}
/>;

プロバイダーの切り替えは 1 行です（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 — 別のアプリに同じウィジェットを組み込んだもの（サブレーンの「2つ目のアプリで動作する」という基準）

2つのプロバイダーを採用する理由

Manteca は LATAM の法定通貨レールを最も幅広く提供しています。Etherfuse は Stellar ネイティブで、ウォレットのオンボーディングをスポンサー付きで提供します。どちらも Stellar 上で USDC を決済します（Manteca は最近 Stellar サポートを追加し、このキットで実環境での動作を検証済みです）。そのため、同じコリドーで複数のアンカーを実際に比較できます。 RampRouter.compareQuotes は1つのリクエストを両方に送り、リアルタイムのレートを並べ替えて返します（検証済み：100 BRL → Etherfuse は 19.49 USDC、Manteca は 19.23 USDC）。 両者が公開する仕組みの考え方はまったく異なります（見積もり／注文と、複数段階のシンセティック＋価格ロック）。このキットはそれらの違いを1つのインターフェースの背後に隠します。これは、この地域でオンランプを統合するアプリが最初に直面する課題そのものです。

	Etherfuse	Manteca	キットが公開するもの
価格設定	見積もり（有効期限2分）	価格ロック（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での決済を確認 → クリック1回で送金された請求可能残高を受け取ります。次に Sell に切り替えると、逆方向の取引を実行できます。ウォレット内で署名してUSDCをBRLに交換し、どちらのトランザクションもStellar Expertにリンクされているため、公開で検証できます。

Mantecaのサンドボックス（https://sandbox.manteca.dev/crypto/v2）を利用するには、Mantecaチームから認証情報を取得する必要があります。アダプターは公開ドキュメントに基づいて実装されており、同じ標準化されたライフサイクルを備えています。

APIキーに関する注意： プロバイダーキーは、KYB、手数料、決済口座を含むご自身のビジネスを識別します。アプリごとに1つあり、サーバー側で保持されるため、エンドユーザーに見えることはありません。ユーザーはその配下の顧客として扱われ、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アンカーのルートです。SepProviderはパートナーキーを必要とせず、エンドユーザーが自身のウォレットで認証するため、フロントエンドのみで実行できます。

テストネットとメインネットの詳細な手順（環境ファイル、単一のRAMP_ENVフラグ、ウォレットネットワーク、認証情報のチェックリスト）については、skills/ramp-kit/references/environments.mdをご覧ください。同じガイドはAIツールにも含まれています。このキットのスキルや@ramp-kit/mcpサーバー（get_documentation → environments）を使うエージェントが、設定を案内できます。

デモをデプロイする（Vercel）

デモはそのままデプロイできる状態で提供されます。サーバーレスプロキシは api/[...path].ts にあり、Vercel によってリポジトリのルートで自動検出されます。

1. vercel.com/new → armandocodecr/latam-ramp-kit をインポートします。
2. Root Directory: ./ · Framework Preset: Other を選択し、Build & Development Settings で次の 3 つを上書きします。
   • 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 は トラストラインの設定と請求を 1 つのトランザクションで行います。

AI ツール：MCP サーバー + エージェントスキル

このキットは、理解と操作の両方を支援する、充実した AI 対応機能を備えています。 AI エージェントがこれらのツールを使って、一連のフローをすでに実行しています。 50 BRL → USDC の見積もりを取得し、サンドボックス注文を作成して、PIX の支払いを シミュレーションし、Stellar Testnet 上で決済されるまで確認しました。

• @ramp-kit/mcp — npm で公開され、公式の MCP Registry に io.github.armandocodecr/ramp-kit として登録されている MCP サーバーです。 9 つのツールを備えています。組み込みドキュメント（6 つのトピックに対応する get_documentation）、プロバイダーの検出、ライブ見積もり、複数プロバイダーの比較、 サンドボックス注文、入金のシミュレーション（設計上、サンドボックス限定）、 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 — エージェントスキルです（Claude Code、Cursor、 および skills CLI がサポートする任意のエージェントに対応）。 このキットが解決する課題、統合フロー、サンドボックスのセットアップ、検証済みの トラブルシューティング、本番環境向けチェックリストをエージェントに教えます。

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

この 2 つを組み合わせると、両方の役割を果たせます。スキルは統合を案内するための 知識をエージェントに与え、MCP サーバーはサンドボックスで見積もり、注文、検証を 実際に行うための手段を提供します。これは Stellar が推進するエージェント型決済の 方向性（x402/MPP）と自然に結び付き、AI エージェントが最初から最後まで理解し、 操作できるランプを実現します。

本番環境への移行

コードは本番環境で使用できる状態です。残る作業はプロバイダーのオンボーディングです。現在、以下の準備が整っています。

• 環境の切り替え — 各プロバイダーの environment: "sandbox" | "production" でベース URL を切り替えます。stellarConfigFor("production") はメインネットの Horizon とネットワークパスフレーズを返します。ハードコードされた発行者はありません。アセットは常にプロバイダー経由で検出されるため、メインネットの識別子が自動的に反映されます。
• サーバー側でのキー管理 — @ramp-kit/server には createRampServer が用意されています。API キーはバックエンドに保持し、ブラウザーからアクセスできるのは許可リストに登録されたランプのエンドポイント（見積もり／注文／ステータス）のみです。また、サンドボックスのシミュレーションエンドポイントは本番環境で完全にブロックされます。
• ポーリングに代わる 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. @ramp-kit/server を HTTPS の背後にデプロイし、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