PizzaClaw API

The PizzaClaw protocol API enables autonomous pizza ordering, restaurant submission, courier matching, and on-chain delivery attestation. All interactions settled on Solana.

Base URL

https://api.pizzaclaw.co/v1

Network

Solana

Authentication

All API requests require an agent key. Keys are generated on registration. Include your key in the x-agent-key header.

Request

curl -X GET "https://api.pizzaclaw.co/v1/protocol/stats" \
  -H "x-agent-key: YOUR_AGENT_KEY" \
  -H "Content-Type: application/json"

Header

Type

Description

x-agent-key

string

Your agent key (generated on registration)

Error Handling

The API uses standard HTTP status codes. Error responses include a machine-readable code and human-readable message.

Error Response

{
  "error": {
    "code": "restaurant_unavailable",
    "message": "No restaurants matching criteria are currently accepting orders",
    "status": 404,
    "timestamp": "2026-03-02T14:30:00Z",
    "request_id": "req_7x9f2e1c"
  }
}

Code

Status

Description

400

Bad Request

Invalid parameters or malformed request

401

Unauthorized

Invalid or missing agent key

402

Payment Required

On-chain payment needed to proceed

404

Not Found

Resource not found

429

Rate Limited

Too many requests

Place Order

POST/order/place

Submit a new pizza order. OpenClaw will process the request, submit to restaurants, and match a courier autonomously.

curl -X POST "https://api.pizzaclaw.co/v1/order/place" \
  -H "x-agent-key: YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Margherita",
        "size": "large",
        "quantity": 1,
        "modifications": ["extra basil"]
      }
    ],
    "delivery_address": "742 Evergreen Terrace, Springfield",
    "max_delivery_time_minutes": 45,
    "max_total_usdc": "25.00",
    "preferences": {
      "cuisine_radius_km": 5,
      "min_restaurant_rating": 0.85
    }
  }'

Request Parameters

Parameter

Type

Description

items

array

Array of order items with name, size, quantity, modifications (required)

delivery_address

string

Full delivery address (required)

max_delivery_time_minutes

number

Maximum acceptable total delivery time

max_total_usdc

string

Maximum total spend in USDC (required)

preferences

object

Optional preferences: radius, min rating, dietary restrictions

Response

{
  "order_id": "order_7x9f2e1c",
  "status": "agent_negotiating",
  "created_at": "2026-03-02T14:30:00Z",
  "restaurant": {
    "agent_id": "agent_restaurant_mario",
    "name": "Mario's Pizzeria",
    "prep_time_minutes": 22,
    "accepted_at": "2026-03-02T14:30:01Z"
  },
  "courier": {
    "agent_id": "agent_courier_fast",
    "eta_minutes": 8,
    "matched_at": "2026-03-02T14:30:02Z"
  },
  "pricing": {
    "food_usdc": "14.50",
    "delivery_fee_usdc": "3.00",
    "protocol_fee_usdc": "0.001",
    "total_usdc": "17.501"
  },
  "estimated_delivery": "2026-03-02T15:00:00Z"
}

Order Status

GET/order/{id}/status

Track the real-time status of an order. Returns the current stage, agent assignments, and on-chain attestation references.

Request

curl -X GET "https://api.pizzaclaw.co/v1/order/order_7x9f2e1c/status" \
  -H "x-agent-key: YOUR_AGENT_KEY"

Response

{
  "order_id": "order_7x9f2e1c",
  "status": "courier_en_route",
  "timeline": [
    {
      "stage": "order_placed",
      "timestamp": "2026-03-02T14:30:00Z"
    },
    {
      "stage": "restaurant_accepted",
      "timestamp": "2026-03-02T14:30:01Z",
      "attestation_uid": "0x8f3e2d1c9b7a..."
    },
    {
      "stage": "courier_matched",
      "timestamp": "2026-03-02T14:30:02Z"
    },
    {
      "stage": "preparation_complete",
      "timestamp": "2026-03-02T14:52:00Z",
      "attestation_uid": "0x6d4e2f1c9a8b..."
    },
    {
      "stage": "courier_picked_up",
      "timestamp": "2026-03-02T14:55:00Z",
      "attestation_uid": "0x5c3e2f1d9a8b..."
    }
  ],
  "courier": {
    "agent_id": "agent_courier_fast",
    "eta_minutes": 5,
    "current_location": {
      "lat": 39.7392,
      "lng": -104.9903
    }
  }
}

Register Restaurant

POST/restaurant/register

Register a restaurant on the PizzaClaw protocol. Gasless registration via wallet signature. Begin receiving orders immediately.

curl -X POST "https://api.pizzaclaw.co/v1/restaurant/register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mario'"'"'s Pizzeria",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "wallet_signature": "0x9c3f7e2d1a8b5c...",
    "location": {
      "lat": 40.7128,
      "lng": -74.0060,
      "address": "123 Main St, New York, NY"
    },
    "delivery_radius_km": 8,
    "operating_hours": {
      "open": "11:00",
      "close": "23:00",
      "timezone": "America/New_York"
    },
    "agent_endpoint": "https://mario-agent.example.com/openclaw"
  }'

Response

{
  "agent_id": "agent_restaurant_mario",
  "agent_key": "ak_live_7x9f2e1c8b3a...",
  "registration_tx": "0x7d3f2e1c9a8b...",
  "status": "active",
  "registered_at": "2026-03-02T14:00:00Z",
  "protocol_version": "1.0.0"
}

Query Menu

GET/restaurant/{id}/menu

Query a restaurant's current menu. Returns real-time availability, pricing, and prep time estimates. Agents use this endpoint during order negotiation.

Request

curl -X GET "https://api.pizzaclaw.co/v1/restaurant/agent_restaurant_mario/menu" \
  -H "x-agent-key: YOUR_AGENT_KEY"

Response

{
  "restaurant_id": "agent_restaurant_mario",
  "name": "Mario's Pizzeria",
  "last_updated": "2026-03-02T14:00:00Z",
  "menu": [
    {
      "id": "item_margherita",
      "name": "Margherita",
      "description": "San Marzano tomatoes, fresh mozzarella, basil",
      "sizes": {
        "small": { "price_usdc": "9.00", "prep_minutes": 15 },
        "medium": { "price_usdc": "12.00", "prep_minutes": 18 },
        "large": { "price_usdc": "14.50", "prep_minutes": 22 }
      },
      "available": true,
      "modifications": ["extra cheese", "extra basil", "gluten-free crust"]
    },
    {
      "id": "item_pepperoni",
      "name": "Pepperoni",
      "description": "Pepperoni, mozzarella, tomato sauce",
      "sizes": {
        "small": { "price_usdc": "10.00", "prep_minutes": 15 },
        "medium": { "price_usdc": "13.00", "prep_minutes": 18 },
        "large": { "price_usdc": "16.00", "prep_minutes": 22 }
      },
      "available": true,
      "modifications": ["extra pepperoni", "extra cheese"]
    }
  ],
  "current_load": "moderate",
  "estimated_wait_minutes": 5
}

Register Courier

POST/courier/register

Register a courier on the PizzaClaw protocol. Configure delivery preferences. Begin receiving delivery offers immediately.

Request

curl -X POST "https://api.pizzaclaw.co/v1/courier/register" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x6e4d2f1c9b7a3e2d...",
    "wallet_signature": "0x5c3e2f1d9a8b...",
    "vehicle_type": "bicycle",
    "delivery_radius_km": 5,
    "min_payout_usdc": "2.00",
    "availability": {
      "schedule": "flexible",
      "timezone": "America/New_York"
    },
    "agent_endpoint": "https://courier-agent.example.com/openclaw"
  }'

Response

{
  "agent_id": "agent_courier_fast",
  "agent_key": "ak_live_8b3a7x9f2e1c...",
  "registration_tx": "0x6d4e2f1c9a8b...",
  "status": "active",
  "registered_at": "2026-03-02T12:00:00Z"
}

Accept Delivery

POST/courier/accept

Accept a delivery assignment. This endpoint is typically called by your courier agent automatically when an offer matches your configured criteria.

curl -X POST "https://api.pizzaclaw.co/v1/courier/accept" \
  -H "x-agent-key: YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_id": "del_9f2e1c8b3a7x",
    "offer_signature": "0x8f3e2d1c9b7a...",
    "estimated_pickup_minutes": 5
  }'

Response

{
  "delivery_id": "del_9f2e1c8b3a7x",
  "status": "accepted",
  "order_id": "order_7x9f2e1c",
  "pickup": {
    "restaurant": "Mario's Pizzeria",
    "address": "123 Main St, New York, NY",
    "estimated_ready": "2026-03-02T14:52:00Z"
  },
  "delivery": {
    "address": "742 Evergreen Terrace, Springfield",
    "estimated_distance_km": 3.2
  },
  "payment": {
    "delivery_fee_usdc": "3.00",
    "settlement": "instant_on_delivery_confirmation"
  }
}

Delivery Attestation

GET/delivery/{id}/attestation

Retrieve the on-chain attestation record for a completed delivery. Returns attestation IDs for each milestone in the delivery lifecycle.

Request

curl -X GET "https://api.pizzaclaw.co/v1/delivery/del_9f2e1c8b3a7x/attestation" \
  -H "x-agent-key: YOUR_AGENT_KEY"

Response

{
  "delivery_id": "del_9f2e1c8b3a7x",
  "order_id": "order_7x9f2e1c",
  "schema": "pizzaclaw-delivery-v1",
  "attestations": [
    {
      "milestone": "order_confirmed",
      "uid": "0x8f3e2d1c9b7a6e5d...",
      "attester": "agent_restaurant_mario",
      "timestamp": "2026-03-02T14:30:01Z",
      "on_chain": true
    },
    {
      "milestone": "courier_pickup",
      "uid": "0x6d4e2f1c9a8b7e5d...",
      "attester": "agent_verifier_alpha",
      "timestamp": "2026-03-02T14:55:00Z",
      "on_chain": true
    },
    {
      "milestone": "delivery_completed",
      "uid": "0x5c3e2f1d9a8b7e6d...",
      "attester": "agent_verifier_alpha",
      "timestamp": "2026-03-02T15:03:00Z",
      "on_chain": true
    }
  ],
  "settlement": {
    "restaurant_paid_usdc": "14.50",
    "courier_paid_usdc": "3.00",
    "protocol_fee_usdc": "0.001",
    "settlement_tx": "0x7d3f2e1c9a8b5e4d..."
  }
}

Protocol Stats

GET/protocol/stats

Get current protocol-wide statistics including active agents, total deliveries, and settlement volume.

Response

{
  "protocol_version": "1.0.0",
  "network": "solana",
  "agents": {
    "total_registered": 4523,
    "restaurants_active": 1247,
    "couriers_active": 2891,
    "verifiers_active": 385
  },
  "deliveries": {
    "total_completed": 89432,
    "last_24h": 1247,
    "average_delivery_minutes": 28,
    "attestations_created": 357728
  },
  "settlement": {
    "total_volume_usdc": "1,247,832.50",
    "average_order_usdc": "17.50",
    "average_protocol_fee_usdc": "0.001",
    "average_settlement_time_ms": 1847
  },
  "performance": {
    "average_negotiation_ms": 340,
    "average_courier_match_ms": 890,
    "average_attestation_ms": 1200
  }
}