Ax402

API reference

Base URL: https://api.archonia.org · HTTPS only · application/json

Overview

Ax402 is an M2M commerce API: generic SKUs paid with USDC via an x402-style 402 challenge, then metered access or a merchant webhook. 

GET  /store/products
POST /store/quotes
POST /store/orders          → 402 + USDC details
     (buyer pays on Base)
POST /store/orders + tx hash → 201 + key or webhook

Prefer the developer guide for a walkthrough. This page is the endpoint map.

GET /store/products

List catalog SKUs. Optional filter: ?merchant_id=…

curl -s https://api.archonia.org/store/products

POST /store/quotes

Create a price quote. Quotes are valid for about one hour.

Request

{
  "product_id": "api-credits-100",
  "quantity": 1
}
Field Type Required Description
product_id string Yes Product slug
quantity integer Yes Number of units

Response 200

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "sku": "api-credits-100",
  "quantity": 1,
  "unit_price": 5,
  "total_price": 5,
  "currency": "USD",
  "valid_until_epoch": 1716474000
}

POST /store/orders

Two-step x402 payment flow.

Step 1 — payment details 402

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "network": "base_sepolia",
  "token": "USDC",
  "amount": "5",
  "recipient_address": "0x…"
}

Send the specified amount of USDC on Base to recipient_address. Keep the transaction hash for step 2.

Step 2 — submit payment 201

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "payment_data": { "hash": "0x…" },
  "ship_to": {
    "name": "Ada Lovelace",
    "line1": "1 Analytical Engine Way",
    "city": "London",
    "postal": "SW1A 1AA",
    "country": "GB"
  }
}
Field Required Description
quote_id Yes Quote UUID from step 1
payment_data.hash Yes USDC transaction hash (0x + 64 hex)
email Recommended Buyer contact for fulfillment
ship_to When required Shipping address for physical SKUs

Success returns order_id, status: "confirmed", plus either an access object (metered) or a fulfillment object (webhook).

Metering endpoints

All require Authorization: Bearer yog_…

Method Path Purpose
GET /v1/balance Credits / quota remaining
POST /v1/meter Consume units (units, optional idempotency_key)
GET /v1/usage Usage history (limit, optional cursor)
GET /v1/usage/export Export (format=json|csv)
POST /v1/keys/rotate Issue a new key; invalidate the old
POST /v1/keys/revoke Revoke the current key

Payment verification

  1. Fetch receipt via RPC (eth_getTransactionReceipt)
  2. Require successful status
  3. Parse the ERC-20 Transfer event from the USDC contract
  4. Verify to matches the configured payout address
  5. Verify amount within 0.01 USDC tolerance

Network and token details are returned in the 402 body. USDC uses 6 decimals.

Errors

HTTP Code Meaning
400 invalid_payment / invalid_input Verify failed or bad body
401 unauthorized Missing or invalid Bearer key
402 Payment required / meter blocked Normal order challenge, or insufficient credits/quota
404 Not found Unknown product, quote, or route
409 payment_already_used Tx hash already consumed
410 quote_expired Quote past expiry
422 product_not_fulfillable Product config incomplete
429 Too Many Requests Rate limit

Complete example

BASE=https://api.archonia.org

QUOTE=$(curl -s -X POST "$BASE/store/quotes" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"api-credits-100","quantity":1}')

QUOTE_ID=$(echo "$QUOTE" | sed -n 's/.*"quote_id":"\([^"]*\)".*/\1/p')

curl -s -X POST "$BASE/store/orders" \
  -H "Content-Type: application/json" \
  -d "{\"quote_id\":\"$QUOTE_ID\"}"

# After sending USDC on Base:
curl -s -X POST "$BASE/store/orders" \
  -H "Content-Type: application/json" \
  -d "{\"quote_id\":\"$QUOTE_ID\",\"email\":\"[email protected]\",\"payment_data\":{\"hash\":\"0xYOUR_TX_HASH\"}}"
Open API Developer guide →