支持的资产与网络

GStable 构建了一个覆盖多条区块链的支付路由网络。与传统支付网关不同，我们实现了支付资产与结算资产的完全解耦。

这意味着，商户可以指定一种资产（如 Polygon 上的 USDC）作为结算货币，而付款用户可以使用 GStable 网络支持的任意链上的任意代币（如 Arbitrum 上的 USDT）进行支付。系统会自动处理跨链兑换和路由。

核心概念

在调用 API 之前，请熟悉 GStable 对资产的定义方式：

Token ID 格式

为了在多链环境下唯一标识一个资产，我们使用 network::symbol 的格式（全小写）作为资产的唯一标识符 (tokenId)。

Token ID	网络 (Chain)	代币 (Token)	精度
`ethereum::usdt`	Ethereum Mainnet (Chain ID 1)	USDT	6
`ethereum::usdc`	Ethereum Mainnet (Chain ID 1)	USDC	6
`base::usdc`	Base (Chain ID 8453)	USDC	6
`arbitrumone::usdt`	Arbitrum One (Chain ID 42161)	USDT	6
`arbitrumone::usdc`	Arbitrum One (Chain ID 42161)	USDC	6
`polygon::usdt`	Polygon PoS (Chain ID 137)	USDT	6
`polygon::usdc`	Polygon PoS (Chain ID 137)	USDC	6

动态获取

支持的资产列表会随着协议升级不断扩充。建议开发者通过 API 动态获取最新列表，而不是在代码中硬编码。

路由与费率机制

GStable 的路由引擎会根据商户选择的结算资产和用户选择的支付资产，自动计算费率和路由路径。

费率模型主要分为两类：

1. 同链支付 (Same-chain)

当用户支付的资产与商户结算的资产在同一条区块链上时，费率最低。

同币种支付：0.2% (2000 PPM) - 使用相同代币直接转账。
不同币种支付（兑换）：0.3% (3000 PPM) - 需要在链上进行代币兑换。
到账时间：极快（取决于区块确认时间，通常 < 10秒）。

2. 跨链支付 (Cross-chain)

当用户支付的资产与商户结算的资产在不同的区块链上时，系统会自动进行跨链桥接。

费率：0.6% (6000 PPM)。
到账时间：包含源链确认和跨链传输时间（通常 30 - 40 秒）。

限额 (Limits)

为了保障路由的成功率，每种交易路径都设有最小和最大支付金额。

同链结算限额

范围：$0.50 ~ $50,000.00（例如，对于 6 位精度的 USDC/USDT 为 5,000,000 ~ 50,000,000,000）。

跨链结算限额（按收款链区分）

Ethereum：$3,500 ~ $50,000
Arbitrum：$10 ~ $50,000
Base：$5 ~ $50,000
Polygon：$20 ~ $50,000

支付能力 (Payment Capabilities)

"支付能力"定义了：当商户决定接收某种资产时，用户可以用什么来支付。

以下是目前主网支持的主要路由路径示例：

结算目标：Ethereum USDT (`ethereum::usdt`)

如果商户创建 Product 时指定 currency 为 ethereum::usdt，用户可选的支付方式包括：

支付网络	支付代币	模式	费率
Ethereum	USDT	同链	0.2%
Ethereum	USDC	同链兑换	0.3%
Base	USDC	跨链	0.6%
Arbitrum	USDC	跨链	0.6%
Arbitrum	USDT	跨链	0.6%
Polygon	USDC	跨链	0.6%
Polygon	USDT	跨链	0.6%

结算目标：Base USDC (`base::usdc`)

如果商户希望在 Base 上接收 USDC，用户可选的支付方式包括：

支付网络	支付代币	模式	费率
Base	USDC	同链	0.2%
Ethereum	USDT	跨链	0.6%
Ethereum	USDC	跨链	0.6%
Arbitrum	USDC	跨链	0.6%
Arbitrum	USDT	跨链	0.6%
Polygon	USDC	跨链	0.6%
Polygon	USDT	跨链	0.6%

结算目标：Arbitrum USDC (`arbitrumone::usdc`)

如果商户希望在 Arbitrum 上接收 USDC，用户可选的支付方式包括：

支付网络	支付代币	模式	费率
Arbitrum	USDC	同链	0.2%
Arbitrum	USDT	同链兑换	0.3%
Ethereum	USDT	跨链	0.6%
Ethereum	USDC	跨链	0.6%
Base	USDC	跨链	0.6%
Polygon	USDC	跨链	0.6%
Polygon	USDT	跨链	0.6%

结算目标：Polygon USDC (`polygon::usdc`)

如果商户创建 Product 时指定 currency 为 polygon::usdc，用户可选的支付方式包括：

支付网络	支付代币	模式	费率
Polygon	USDC	同链	0.2%
Polygon	USDT	同链兑换	0.3%
Ethereum	USDT	跨链	0.6%
Ethereum	USDC	跨链	0.6%
Base	USDC	跨链	0.6%
Arbitrum	USDC	跨链	0.6%
Arbitrum	USDT	跨链	0.6%

查询能力 API

由于支持的网络和代币对经常更新，GStable 提供了一个公共接口来查询当前系统的完整路由能力。

获取能力配置

GET [/api/v1/common/capability](https://api.gstable.io/public/api/v1/capabilities/all)

此接口返回当前支持的所有 supportedTokens 以及详细的 paymentCapabilities 矩阵，包含最新的费率 (feeRatePPM) 和限额配置。

响应示例：

{
  "code": 0,
  "message": "",
  "data": {
    "supportedTokens": [
      {
        "tokenId": "ethereum::usdt",
        "symbol": "USDT",
        "chainId": "1",
        "decimals": 6
      },
      {
        "tokenId": "ethereum::usdc",
        "symbol": "USDC",
        "chainId": "1",
        "decimals": 6
      },
      {
        "tokenId": "base::usdc",
        "symbol": "USDC",
        "chainId": "8453",
        "decimals": 6
      },
      {
        "tokenId": "arbitrumone::usdt",
        "symbol": "USDT",
        "chainId": "42161",
        "decimals": 6
      },
      {
        "tokenId": "arbitrumone::usdc",
        "symbol": "USDC",
        "chainId": "42161",
        "decimals": 6
      },
      {
        "tokenId": "polygon::usdt",
        "symbol": "USDT",
        "chainId": "137",
        "decimals": 6
      },
      {
        "tokenId": "polygon::usdc",
        "symbol": "USDC",
        "chainId": "137",
        "decimals": 6
      }
    ],
    "paymentCapabilities": {
      "polygon::usdc": {
        "POL": [
          {
            "tokenId": "polygon::usdc",
            "crosschain": false,
            "feeRatePPM": 2000, // 0.2% - 同链同币种
            "minPaymentValue": 5000000, // $5 最低限额
            "maxPaymentValue": 50000000000 // $50,000 最高限额
          },
          {
            "tokenId": "polygon::usdt",
            "crosschain": false,
            "feeRatePPM": 3000, // 0.3% - 同链兑换
            "minPaymentValue": 5000000,
            "maxPaymentValue": 50000000000
          }
        ],
        "ARB": [
          {
            "tokenId": "arbitrumone::usdc",
            "crosschain": true,
            "feeRatePPM": 6000, // 0.6% - 跨链
            "minPaymentValue": 10000000, // Arbitrum 收款最低 $10
            "maxPaymentValue": 50000000000
          }
        ],
        "ETH": [
          {
            "tokenId": "ethereum::usdc",
            "crosschain": true,
            "feeRatePPM": 6000,
            "minPaymentValue": 20000000, // Polygon 收款最低 $20
            "maxPaymentValue": 50000000000
          }
        ]
      }
    }
  }
}

前端集成

如果你正在构建自定义前端，你应该调用此接口来渲染用户的“支付方式选择器”，并根据 feeRatePPM 向用户展示预估费用。

核心概念​

Token ID 格式​

路由与费率机制​

1. 同链支付 (Same-chain)​

2. 跨链支付 (Cross-chain)​

限额 (Limits)​

同链结算限额​

跨链结算限额（按收款链区分）​

支付能力 (Payment Capabilities)​

结算目标：Ethereum USDT (ethereum::usdt)​

结算目标：Base USDC (base::usdc)​

结算目标：Arbitrum USDC (arbitrumone::usdc)​

结算目标：Polygon USDC (polygon::usdc)​

查询能力 API​

获取能力配置​