x402 payments

The flow

A request with no key that is over the keyless daily limit, or a key that is out of credits, gets 402 Payment Required. The body lists every offer in accepts (x402 version 2). The same object is in the payment-required header.

curl -i "https://api.tide.ad/v1/coins/0x2::sui::SUI"
# HTTP/2 402
# payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...   (base64 JSON, same object as the body)

# build and sign the payment for one offer in accepts, then:

curl -i "https://api.tide.ad/v1/coins/0x2::sui::SUI" \
  -H "PAYMENT-SIGNATURE: BASE64_PAYMENT"
# HTTP/2 200
# payment-response: eyJzdWNjZXNzIjp0cnVlLi4u
# x-tide-api-key: tide_...

Offers

Each offer has scheme exact, network sui:mainnet, an amount in raw USDC (6 decimals), the USDC asset, and payTo, the tide treasury. GET /v1/billing/offers returns them with no key.

Pay and retry

1. Build a gasless transaction that sends exactly amount of the asset to payTo with balance::send_funds. Use gas price 0, budget 0, no gas coins, and a ValidDuring expiration from extra.validDuring.
2. Sign it.
3. Retry the same request with the header PAYMENT-SIGNATURE (or X-PAYMENT) set to base64 JSON { x402Version: 2, accepted: <the offer>, payload: { signature, transaction } }.

tide checks the exact amount, the recipient, the single-use nonce and the expiry, submits the transaction, waits for finality and answers the call. The response carries PAYMENT-RESPONSE and X-Tide-Api-Key.

POST /v1/billing/pay settles a payment without calling anything else and returns the digest, the payer, the credits and the key.

Session key

Every payment's credits go to an account owned by the payer address. X-Tide-Api-Key is a key derived from that address, the same key every time, so one $1 or $10 payment buys a session. Use it as Authorization: Bearer.