docs.p3p.xyz

中文

English
Italiano
Français
Español
Svenska
العربية
Русский

中文

English
Italiano
Français
Español
Svenska
العربية
Русский

主题

交易所 API 📝 ​

介绍 ​

交易所 API 是 p3p 的核心交易接口。使用它来发现可交易的内容，获得跨所有聚合流动性来源的最佳报价，将该报价锁定到链上交易，并跟踪其完成情况。

下面的所有端点都需要开发者 api-key 标头。在 p3p.xyz 注册为合作伙伴即可获取。

http
api-key: YOUR_P3P_API_KEY

端点 ​

1. 获取链2. 获取代币3. 获取汇率4. 报价交易所汇率5. 创建交易所6. 检查交易所状态7. 检查多个交易所

1. 获取链 ​

GET /chains 需要 api-key

返回 p3p 上当前启用的每条链。

bash
curl https://api.p3p.xyz/chains \
  -H "api-key: YOUR_P3P_API_KEY"
ts
const chains = await fetch("https://api.p3p.xyz/chains", {
  headers: { "api-key": "YOUR_P3P_API_KEY" },
}).then((r) => r.json());
json
{
  "status": 200,
  "message": "ok",
  "data": [
    {
      "id": 0,
      "key": "btc",
      "name": "Bitcoin",
      "display": "BTC Chain",
      "color": "#F7931A",
      "logo": "",
      "icon": "token:btc",
      "explorer": {
        "address": "https://mempool.space/address/%s",
        "tx": "https://mempool.space/tx/%s"
      },
      "website": "https://bitcoin.org",
      "vm": "BVM",
      "validation": [
        "^(1[1-9A-HJ-NP-Za-km-z]{25,34}|3[1-9A-HJ-NP-Za-km-z]{25,34}|bc1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{8,87})$"
      ],
      "defaults": ["btc"],
      "tags": ["bitcoin", "btc", "xbt", "satoshi"],
      "enabled": true
    },
    {
      "id": 1,
      "key": "eth",
      "name": "Ethereum",
      "display": "ETH Chain",
      "color": "#627EEA",
      "logo": "",
      "icon": "token:eth",
      "explorer": {
        "address": "https://etherscan.io/address/%s",
        "tx": "https://etherscan.io/tx/%s"
      },
      "website": "https://ethereum.org",
      "vm": "EVM",
      "validation": [
        "^(0x)[0-9A-Fa-f]{40}$"
      ],
      "defaults": ["eth", "usdt", "usdc", "dai"],
      "tags": ["ethereum", "eth", "eht", "vitalik"],
      "enabled": true
    }
  ]
}

2. 获取代币 ​

GET /tokens 需要 api-key

返回按链分组的已启用代币。

bash
curl https://api.p3p.xyz/tokens \
  -H "api-key: YOUR_P3P_API_KEY"
json
{
  "eth": [
    { "key": "eth", "name": "Ether", "symbol": "ETH", "decimals": 18, "rate": "3421.8", "address": "", "native": true, "enabled": true },
    { "key": "usdt", "name": "Tether", "symbol": "USDT", "decimals": 6, "rate": "1.0", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "native": false, "enabled": true }
  ],
  "ton": [
    { "key": "ton", "name": "Toncoin", "symbol": "TON", "decimals": 9, "rate": "5.23", "address": "", "native": true, "enabled": true },
    { "key": "usdt", "name": "USDT (TON)", "symbol": "USDT", "decimals": 6, "rate": "1.0", "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", "native": false, "enabled": true }
  ]
}

3. 获取汇率 ​

GET /rates 需要 api-key

返回每个受支持资产的实时市场参考汇率，来源于链上预言机。

bash
curl https://api.p3p.xyz/rates \
  -H "api-key: YOUR_P3P_API_KEY"
json
{
  "btc": 98234.56,
  "eth": 3421.8,
  "ton": 5.23,
  "usdt": 1.0,
  "usdc": 1.0,
  "sol": 142.35
}

4. 报价交易所汇率 ​

POST /exchange/rate 需要 api-key

聚合每个活跃流动性来源的汇率并返回最佳（或全部）。

请求体

字段类型必需描述
chain_fromstring是源链密钥
token_fromstring是源代币密钥
amount_fromstring是显示单位的数量
chain_tostring是目标链密钥
token_tostring是目标代币密钥
opts.bestboolean否按最佳汇率排序（默认）
opts.fastestboolean否按最快汇率排序而不是最佳
opts.partner_idstring否您的合作伙伴 ID 或注册錢包（赚取收入）
bash
curl -X POST https://api.p3p.xyz/exchange/rate \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{
    "chain_from": "eth",
    "token_from": "eth",
    "amount_from": "0.1",
    "chain_to": "ton",
    "token_to": "ton",
    "opts": { "best": true }
  }'
ts
const rate = await fetch("https://api.p3p.xyz/exchange/rate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_P3P_API_KEY",
  },
  body: JSON.stringify({
    chain_from: "eth",
    token_from: "eth",
    amount_from: "0.1",
    chain_to: "ton",
    token_to: "ton",
    opts: { best: true },
  }),
}).then((r) => r.json());
json
{
  "type": "crypto",
  "path_from": "eth.eth",
  "path_to": "ton.ton",
  "amount_from": "0.1",
  "amount_to": "342.18",
  "direction": "exact_input",
  "amount_from_unit": 0.1,
  "amount_to_unit": 342.18,
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90,
  "boosted": false
}

5. 创建交易所 ​

POST /exchange/create 需要 api-key

锁定汇率，创建交易所并接收存款地址。

请求体

字段类型必需描述
chain_fromstring是源链密钥
token_fromstring是源代币密钥
amount_fromstring是显示单位的数量
chain_tostring是目标链密钥
token_tostring是目标代币密钥
wallet_tostring是目标链上的接收者地址
wallet_refundstring否如果交易无法完成时的退款地址
wallet_fromstring否用户的源地址（某些链需要）
opts.bestboolean否按最佳汇率排序（默认）
opts.fastestboolean否按最快汇率排序而不是最佳
opts.partner_idstring否您的合作伙伴 ID 或注册錢包（赚取收入）
bash
curl -X POST https://api.p3p.xyz/exchange/create \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{
    "chain_from": "eth", "token_from": "eth", "amount_from": "0.1",
    "chain_to":   "ton", "token_to":   "ton",
    "wallet_to":     "UQAbc...XYZ",
    "wallet_refund": "0xRefund...address",
    "opts": { "partner_id": "P3_YOURPARTNERID" }
  }'
ts
const exchange = await fetch("https://api.p3p.xyz/exchange/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_P3P_API_KEY",
  },
  body: JSON.stringify({
    chain_from: "eth",
    token_from: "eth",
    amount_from: "0.1",
    chain_to: "ton",
    token_to: "ton",
    wallet_to: "UQAbc...XYZ",
    wallet_refund: "0xRefund...address",
    opts: { partner_id: "P3_YOURPARTNERID" }, 
  }),
}).then((r) => r.json());
json
{
  "created_at": "2026-05-24T10:30:00Z",
  "id": "ex_8f4c2a...",
  "type": "crypto",
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_refund": "0xRefund...address",
  "wallet_from": "",
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90
}

合作伙伴交易所（使用 api-key 标头时）：响应返回 hash 而不是 id：

json
{
  "created_at": "2026-05-24T10:30:00Z",
  "hash": "A7K2M9X5B3C1D8F4",
  "type": "crypto",
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90
}

从您的钱包向 deposit_address 发送 amount_from 的 token_from 以启动交易。使用下面的检查交易所状态跟踪进度。

合作伙伴交易所是私有的

合作伙伴交易所（通过 hash 标识）只能通过将 hash 作为 ID 并使用您的 api-key 标头来访问。它们无法通过普通交易 ID 查询。

存款窗口

存款必须完全匹配 amount_from 并在约 6 分钟内到达。超时后，您可以在状态端点上使用 ?bump=true 重试。

6. 检查交易所状态 ​

GET /check/:txId 需要 api-key

获取单个交易所或发票的当前状态。

查询类型描述
bumpboolean如果 true，重试停滞/超时的交易所
bash
curl https://api.p3p.xyz/check/ex_8f4c2a... \
  -H "api-key: YOUR_P3P_API_KEY"
json
{
  "id": "ex_8f4c2a...",
  "created_at": "2026-05-24T10:30:00Z",
  "status": "exchanging",
  "type": "internal",
  "invoice": false,
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "checkpoint": 3,
  "checkpoints": 5
}

状态值 ​

状态含义
new等待用户存款
deposited检测到存款，正在准备交换
processing交换已提交至流动性来源，等待确认
exchanging交换已确认，资金正在兑换中
complete完成 — 接收者已收到资金
timeout存款窗口已过期；使用 ?bump=true 重置并重试
error交易遇到错误；使用 ?bump=true 重试
expired交易已过期，无法再重试

Bump 重试 ​

如果交易超时（在存款窗口内未检测到存款），请再次使用 ?bump=true 调用端点以重置窗口：

bash
curl "https://api.p3p.xyz/check/ex_8f4c2a...?bump=true" \
  -H "api-key: YOUR_P3P_API_KEY"

合作伙伴交易所（使用 api-key 标头创建的）可以通过将 hash 作为 ID 来查询。如果存在 api-key 标头，系统会自动先尝试将其匹配为 hash：

bash
# 使用合作伙伴 api-key — 按哈希查询
curl https://api.p3p.xyz/check/A7K2M9X5B3C1D8F4 \
  -H "api-key: YOUR_PARTNER_API_KEY"
json
{
  "hash": "A7K2M9X5B3C1D8F4",
  "created_at": "2026-05-24T10:30:00Z",
  "status": "complete",
  "type": "internal",
  "invoice": false,
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "checkpoint": 5,
  "checkpoints": 5
}

哈希格式

默认情况下，哈希为 40 个字母数字字符 (a-z, A-Z, 0-9)。合作伙伴可以通过合作伙伴控制台自定义格式。

7. 检查多个交易所 ​

POST /check 需要 api-key

在一次调用中检查多个交易。

请求体

字段类型必需描述
hashesstring[]是交易所 ID 数组
bash
curl -X POST https://api.p3p.xyz/check \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{ "hashes": ["ex_8f4c2a...", "ex_aa11bb..."] }'

返回精简交易状态对象数组：

json
[
  {
    "hash": "ex_8f4c2a...",
    "status": "complete",
    "type": "crypto",
    "invoice": false,
    "chain_from": "eth",
    "token_from": "eth",
    "amount_from": "0.1",
    "chain_to": "ton",
    "token_to": "ton",
    "amount_to": "342.18",
    "checkpoint": 4,
    "checkpoints": 4
  },
  {
    "hash": "A7K2M9X5B3C1D8F4",
    "status": "exchanging",
    "type": "crypto",
    "invoice": false,
    "chain_from": "ton",
    "token_from": "usdt",
    "amount_from": "100",
    "chain_to": "eth",
    "token_to": "usdc",
    "amount_to": "99.5",
    "checkpoint": 2,
    "checkpoints": 4
  }
]