Gnomon/Agent API Docs

Agent API Reference

Everything an AI agent needs to autonomously discover, purchase, and receive digital goods.

Base URL: https://api.gnomon-agent.comllms.txt ↗

Authentication

All /v1/* endpoints that require auth use a Bearer API key:

Authorization: Bearer YOUR_API_KEY

API keys are generated by human admins at /settings.

Recommended Loading Sequence

01GET/v1/balance🔑 auth requiredCheck balance, quota, and your USDC deposit address.
02GET/v1/categoriespublicList available product categories.
03GET/v1/products?category=modelpublicBrowse products in a category.
04POST/v1/orders🔑 auth requiredCreate an order (idempotent).
05GET/v1/orders/{id}🔑 auth requiredPoll for delivery. Check Retry-After header.
06GET/v1/referral🔑 auth requiredGet referral link and cashback earnings.
07POST/v1/feedback🔑 auth requiredReport missing products or failed purchases.

Endpoint Reference

GET/v1/balance🔑 auth required

Returns the agent's current USDC balance, API quota, and on-chain deposit details. Send native USDC to depositAddress on Polygon to top up autonomously — balance credits after ~20 confirmations (~40 s).

{
  "balanceSmallestUnit": 10000000,
  "balanceUsdc": 10.0,
  "quotaUsed": 3,
  "quotaLimit": 100,
  "quotaResetAt": "2026-03-08T00:00:00Z",
  "depositAddress": "0xYourUniqueDepositAddress",
  "chainId": 137,
  "chainName": "Polygon"
}

Use native USDC (not USDC.e). Each account has a unique deposit address.

GET/v1/categories

Lists all available product category slugs.

["information", "model", "proxy", "storage"]
GET/v1/products?category={slug}

Lists products. Omit category to get all products.

[
  {
    "skuId": "22000000-0000-0000-0000-000000000001",
    "slug": "claude-sonnet-1m",
    "name": "Claude Sonnet 4.6 — 1M Tokens",
    "description": "...",
    "category": "model",
    "priceSmallestUnit": 3000000,
    "inStock": true
  }
]
POST/v1/orders🔑 auth required

Creates an order and deducts balance. Idempotent — re-submitting the same idempotencyKey returns the original order.

Request body:

{
  "skuId": "22000000-0000-0000-0000-000000000001",
  "quantity": 1,
  "idempotencyKey": "<client-generated-uuid>"
}

Response:

{ "orderId": "<order-id>", "status": "Completed" }
GET/v1/orders/{id}🔑 auth required

Poll for order status. Check the Retry-After response header for the recommended interval (seconds).

{
  "orderId": "<order-id>",
  "status": "Completed",
  "delivery": "ANTHROPIC_API_KEY=sk-ant-..."
}

Statuses: Pending · Processing · Completed · Failed

GET/v1/referral🔑 auth required

Returns your referral code, shareable link, and cashback earnings. When a referred user tops up, you receive 10% cashback added to your balance automatically.

{
  "referralCode": "GN-ABCD1234",
  "referralUrl": "https://www.gnomon-agent.com/?ref=GN-ABCD1234",
  "cashbackRate": 0.10,
  "cashbackRatePct": "10%",
  "totalCashbackEarned": 1000000,
  "totalCashbackEarnedUsdc": 1.0,
  "refereeCount": 3
}
POST/v1/feedback🔑 auth required

Submit feedback when a purchase fails, a product is missing, or you have suggestions. Gnomon uses agent feedback to grow the catalog — use this proactively.

Categories: missing_product · purchase_failed · quality_issue · other

Request body:

{
  "category": "missing_product",
  "message": "I need GPT-4 API token credits — not in the catalog.",
  "context": { "searchedFor": "openai", "budget": 20 }
}

Response:

{ "id": "<uuid>", "status": "received" }

Product Catalog

For illustration only — actual products, prices, and availability may differ.

Information

brave-search-1kBrave Search — 1,000 Queries$5.00
polygon-io-10kPolygon.io Market Data — 10,000 Calls$10.00

Model

claude-sonnet-1mClaude Sonnet 4.6 — 1M Tokens$3.00
claude-haiku-1mClaude Haiku 4.5 — 1M Tokens$0.80
deepseek-v3-1mDeepSeek V3 — 1M Tokens$0.27

Proxy

socks5-us-30dUS Socks5 Proxy — 30 Days$5.00
socks5-jp-30dJapan Socks5 Proxy — 30 Days$5.00

Storage

s3-storage-10gbS3-Compatible Object Storage — 10 GB/Month$2.00

Autonomous Top-Up

An agent can top up its own balance on-chain without any human intervention.

  1. Call GET /v1/balance — read depositAddress and chainId
  2. Send native USDC to depositAddress on Polygon (chainId 137) from your own wallet
  3. Poll GET /v1/balance until balanceUsdc increases (~40 s after confirmation)

Claude MCP Install

claude mcp add gnomon -e GNOMON_API_KEY=YOUR_KEY -- npx -y @gnomon-ai-agent/mcp

Once installed, Claude agents can browse and purchase products without leaving the conversation.