openfin-onramp

法币入金（Moonpay + Onramp.money）

发布方。 属于 OpenFinance 技能套件的一部分（openfin-setup、openfin-troubleshooting、openfin-hyperliquid、openfin-relay、openfin-onramp、openfin-polymarket、openfin-onchain）——均由 OpenFinance（https://openfinance.tech）维护。请作为一套安装，不要单独安装。

两个服务商，一个智能路由端点：

服务商	支付方式	最适用于	baseCurrency
Moonpay	银行卡、Apple Pay、Google Pay、SEPA、银行转账	全球／非 INR	usd、eur、gbp、…
Onramp.money	UPI、IMPS、银行转账	印度／INR	inr（仅此项）

Agent 不会在链上签名——用户打开返回的 URL，完成 KYC 和付款。

前提条件

1. 已完成 openfin-setup。
2. 已为用户配置目标链的钱包（默认 EVM；如果 chain=solana / currencyCode=*_sol，则必须启用 Solana）。

端点

POST /agent/onramp — 智能路由器（默认）

baseCurrency: "inr" → Onramp.money。其他任何值（或未提供时 → 默认为 usd）→ Moonpay。请求体接受两者字段的并集；路由器 只转发相关字段。

字段	说明
baseCurrency	路由键，会转换为小写。默认值为 "usd"。
chain	ethereum / polygon / base / arbitrum / optimism / bsc / tron / solana。（Onramp.money 仅支持其中一部分，见支持矩阵。）
currency	加密货币代码（usdc、usdt、eth、sol、btc、…）。
amount	用户要支付的法币金额。
walletAddress	可选；默认使用调用方在该链上的钱包地址。
redirectURL	成功后服务商会重定向到此处。

响应：{ provider: "moonpay" | "onrampmoney", url: "https://…" }。

常见 Moonpay currencyCode 推导规则（智能路由器根据 chain + currency 选择 Moonpay 时）：Ethereum 上的 eth / usdc → eth / usdc；Polygon/Base/Arbitrum/Optimism 上的 usdc → usdc_polygon / usdc_base / usdc_arbitrum / usdc_optimism；Solana 上的 sol → sol，Solana 上的 usdc → usdc_sol。如果不确定，智能路由器也接受 currencyCode 并会直接转发。

仅限 Moonpay / 仅限 Onramp.money 的 REST 路由 （POST /agent/onramp/moonpay、POST /agent/onramp/onrampmoney）仍然 存在，供仪表板和直接 API 调用方使用，但不会作为 MCP 操作公开—— Agent 应始终使用智能路由器，以确保 baseCurrency: "inr" 正确路由到 Onramp.money。以下强制选择服务商的字段仅为完整起见而记录（仅供 REST 调用方使用）。

POST /agent/onramp/onrampmoney — 仅限 REST（仪表板）

字段	说明
chain	ethereum / polygon / bsc / tron / solana。映射到旧版 network 代码。
network	旧版代码（erc20 / matic20 / bep20 / trc20 / spl）；优先于 chain 映射。
currency / coinCode	币种（usdc、usdt、busd、matic、bnb、eth、sol）。
amount	INR（例如 1000 = ₹1000）。
coinAmount	加密货币侧的目标金额——如果同时传入两者，则优先使用此值。
paymentMethod	1 = UPI/即时支付（印度默认值），2 = IMPS/银行转账。不传则由用户选择。
walletAddress、redirectURL、addressTag	可选。

链 → Onramp network：ethereum→erc20、polygon→matic20、 bsc→bep20、tron→trc20、solana→spl。

Onramp.money 支持矩阵（币种 × 网络）

不在此矩阵内的调用会报错。请推荐受支持的组合，或改用 Moonpay。

币种	网络
usdt	bep20、matic20、erc20、trc20
usdc	bep20、matic20（不支持 erc20 / solana）
busd	bep20
matic	matic20
bnb	bep20
eth	erc20、matic20
sol	spl

接近支持范围但需要即时调整的情况：

• “用 INR 在 Ethereum 上购买 USDC” → 推荐 Polygon（或 Moonpay）。
• “用 INR 在 Solana 上购买 USDC” → 推荐 Polygon / BSC（或 Moonpay）。
• “用 INR 在 Arbitrum / Base / Optimism 上购买 ETH” → 在 Eth/Polygon 上入金， 然后通过 openfin-relay 跨链桥接，或使用 Moonpay。

钱包默认值

如果省略 walletAddress：EVM chain → 调用者的 EVM 地址； chain=solana 或 currencyCode=*_sol → 调用者的 Solana 地址。 缺少钱包 → 请求失败；请引导用户访问 openfinance.tech。

与其他技能搭配使用

• 入金服务将资金转入链 X，而用户想在链 Y 上交易 → 通过 openfin-relay 跨链桥接。
• Arbitrum 上的 USDC → Hyperliquid → 使用 GET /agent/trading/deposit-address。 Hyperliquid 仅接受 USDC（不接受 USDT 或 USDC.e）。
• INR → Hyperliquid：通过 Onramp.money 将 INR 换成 Polygon 或 BSC 上的 USDC → 使用 openfin-relay 跨链桥接至 Arbitrum → Hyperliquid 存款地址。
• Polygon 上的 USDC → Polymarket → 换成 pUSD 并转入存款钱包（GET /agent/polymarket/deposit-wallet）。

示例

USD → Base 上的 USDC（Moonpay）：

POST /agent/onramp
{ "chain": "base", "currency": "usdc", "amount": 100, "baseCurrency": "usd" }
→ { "provider": "moonpay", "url": "https://buy.moonpay.com/?…" }

INR → 通过 UPI 换成 Polygon 上的 USDC（Onramp.money）：

POST /agent/onramp
{ "baseCurrency": "inr", "chain": "polygon", "currency": "usdc",
  "amount": 5000, "paymentMethod": 1 }
→ { "provider": "onrampmoney", "url": "https://onramp.money/app/?…" }

不要这样做

• 不要使用 Onramp.money 处理非 INR 法币——它仅支持 INR。
• 不要忽略（币种 × 网络）矩阵——应推荐受支持的组合，而不是重试。
• 不要索要银行卡或 UPI 详细信息——服务提供商会在其自己的 KYC 界面中收集这些信息。
• 不要轮询入金状态——服务提供商会直接将资金转入钱包。请通过 openfin-onchain（/balances）在链上确认。

MCP

单个工具：get_onramp_url（智能路由器）。请求体与 POST /agent/onramp 相同；返回 { provider, url, … }。强制指定服务提供商的路由仅支持 REST——没有 get_moonpay_onramp_url 或 get_onrampmoney_onramp_url MCP 操作， 因此所有入金服务调用都会经过智能路由器。INR 相关触发词 （“用 INR 购买 USDT”、“存入 ₹1000”、“通过 UPI 获取 USDC”）会自动路由至 Onramp.money。