Apiosk Gateway

Listing types

• Public browse groups:
  • api
  • datasets
  • compute
• Internal listing types supported by the gateway data model:
  • api
  • skill
  • product
  • dataset
  • service
  • connector

For discovery, always start with:

1. GET /types
2. GET /types/<group>/v1
3. GET /v1/apis with search, category, sort, order, limit, offset

Payment flow (x402)

1. Send the request without x-payment.
2. If response is 402, parse accepts[0] from JSON:
   • scheme
   • network
   • maxAmountRequired
   • payTo
   • asset
   • maxTimeoutSeconds
   • extra.name and extra.version (token EIP-712 domain)
3. Build a TransferWithAuthorization payload and sign it with EIP-712.
4. Create proof:
   • x402Version: 1
   • scheme
   • network
   • payload.signature
   • payload.authorization (from, to, value, validAfter, validBefore, nonce)
5. Base64-encode the proof JSON.
6. Retry the exact same HTTP method/path/body with header x-payment: <base64-proof>.

If the retry returns 402 again, generate a new nonce and fresh validBefore and retry once more.

Create payment proof (reference)

Use EIP-3009 TransferWithAuthorization typed data:

• Domain:
  • name = requirement.extra.name (fallback USD Coin)
  • version = requirement.extra.version (fallback 2)
  • chainId from requirement.network
  • verifyingContract = requirement.asset
• Types:
  • from, to, value, validAfter, validBefore, nonce
• Message:
  • from = caller wallet
  • to = requirement.payTo
  • value = requirement.maxAmountRequired
  • validAfter = 0
  • validBefore = now + requirement.maxTimeoutSeconds
  • nonce = random 32-byte hex

Network-to-chainId defaults:

• base-sepolia => 84532
• base => 8453
• ethereum => 1
• polygon => 137
• arbitrum => 42161

Publishing APIs (upload flow)

Use POST /v1/apis/register with JSON:

{
  "name": "My API",
  "slug": "my-api",
  "endpoint_url": "https://example.com",
  "price_usd": 0.01,
  "description": "My paid API",
  "owner_wallet": "0x...",
  "category": "data"
}

Required auth headers for register/update/mine/delete:

• x-wallet-address
• x-wallet-signature
• x-wallet-timestamp
• x-wallet-nonce

Canonical signed message:

Apiosk auth