X402 Facilitator інтеграція

https://facilitator.acedata.cloud

​

v2 wire угода

• Заголовок запиту - PAYMENT-SIGNATURE, значення - base64 закодований JSON envelope.
• Верхній рівень envelope повинен бути x402Version: 2, і за допомогою об’єкта accepted оголошується вибраний scheme та network.
• network використовує ідентифікатор CAIP-2 (наприклад, eip155:8453), не можна використовувати скорочення на кшталт base.

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453"
  },
  "payload": { "...": "..." }
}

​

Основний інтерфейс

​

GET /supported

curl https://facilitator.acedata.cloud/supported

{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:8453",
      "extra": { "facilitatorAddress": "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708" }
    },
    { "x402Version": 2, "scheme": "exact", "network": "eip155:1187947933" },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": { "feePayer": "3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq" }
    }
  ],
  "extensions": [],
  "signers": {
    "eip155:*": [
      "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708",
      "0xd0479FA9FD8C678303d477433d24C15e3723CC1C"
    ],
    "solana:*": ["3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq"]
  }
}

• network використовує ідентифікатор CAIP-2, не є скороченням на кшталт base, skale.
• /supported вказує, що Facilitator має відповідні можливості верифікації та розрахунків.
• Base, SKALE та Solana підтримують exact; upto наразі доступний лише на Base.
• signers - це адреси, які Facilitator використовує для подання транзакцій розрахунків.
• Чи дозволяє конкретний API ці варіанти, все ще залежить від accepts цього API.

​

POST /verify

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "eip155:8453"
    },
    "payload": { "...": "..." }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x...",
    "amount": "95215",
    "payTo": "0x...",
    "maxTimeoutSeconds": 3600,
    "extra": { "...": "..." }
  }
}

{
  "isValid": true,
  "invalidReason": null,
  "payer": "0x..."
}

settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151', 'errorReason': None}
order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402 price 1.2
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC

• success=True вказує на успішне завершення розрахунків Facilitator.
• transaction - це хеш транзакції в ланцюзі, pay_id замовлення також записується в те саме значення.
• На explorer можна побачити переказ 1200000 atomic USDC.
• errorReason=None вказує на те, що під час цього розрахунку не було повернуто бізнес-ошибок.

​

POST /settle

{
  "success": true,
  "errorReason": null,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0x...",
  "amount": "3"
}

​

Як Ace Data Cloud Gateway використовує Facilitator

1. Клієнт вперше запитує API, не надаючи Authorization та PAYMENT-SIGNATURE.
2. Gateway розраховує попередню ціну запиту, повертає 402 та accepts.
3. Клієнт підписує та повторно надає PAYMENT-SIGNATURE.
4. Gateway декодує PAYMENT-SIGNATURE, вибирає відповідні вимоги до оплати.
5. Gateway викликає Facilitator /verify.
6. Після успішного /verify Gateway пропускає запит до цільового API.
7. Після повернення цільового API Gateway на етапі /record викликає Facilitator /settle.
8. Gateway записує хеш транзакції в ланцюзі в метадані використання. exact на кроці 7 розрахунок суми підпису; upto на кроці 7 відповідно до реального використання записати amount, а потім розрахувати фактичну суму.

​

Як підключити свій API

1. Підготуйте paymentRequirements для кожного платного інтерфейсу, що містить мережу, суму, адресу отримувача, адресу активу та домен підпису.
2. Якщо запит не містить PAYMENT-SIGNATURE, поверніть HTTP 402 та accepts.
3. Якщо запит містить PAYMENT-SIGNATURE, декодуйте Base64, щоб отримати paymentPayload.
4. Викликайте Facilitator /verify.
5. Після успішної перевірки виконуйте бізнес-логіку.
6. Після успішного виконання бізнесу викликайте Facilitator /settle.
7. Збережіть payer, transaction, amount, network для звірки.

​

Захист від повторних запитів

• Клієнт повинен підписувати новий envelope з кожним запитом;
• Якщо /settle вже надіслав транзакцію, але поки що не підтверджена, можна повторно спробувати /settle з тим же nonce для ідентного звіряння;
• Не зберігайте один і той же PAYMENT-SIGNATURE для багаторазових викликів API.

​

Загальні помилки