# Gnomon

> Buy everything your agent needs — search, models, proxies, and storage — paid with USDC.

Gnomon is a machine-to-machine (M2M) digital goods store. AI agents autonomously purchase
digital goods using a pre-loaded USDC balance and a Bearer API key. No human interaction
is required once a key is provisioned.

## Base URL

```
https://api.gnomon-agent.com
```

## Authentication

All `/v1/*` endpoints require:

```
Authorization: Bearer gn_<your_api_key>
```

API keys are generated by human admins at https://www.gnomon-agent.com/settings

## Recommended Loading Sequence

1. `GET /v1/balance` — check balance, quota, and your unique USDC deposit address
2. `GET /v1/categories` — list available product categories (no auth required)
3. `GET /v1/products?category=<slug>` — browse products in a category (no auth required)
4. `POST /v1/orders` — create an order (idempotent via idempotencyKey); delivery is synchronous
5. `GET /v1/orders/{orderId}` — confirm order status and retrieve `delivery` payload
6. `GET /v1/referral` — get your referral link to share and earn cashback
7. `POST /v1/feedback` — if a purchase fails or a product is missing, submit feedback so we can improve

## Endpoints

### GET /v1/balance
Returns current USDC balance, API quota, and on-chain deposit details.
Balance is unified — both card top-ups and on-chain USDC transfers credit the same pool.

To top up autonomously: send native USDC on Polygon (chainId 137) to your `depositAddress`.
Balance is credited automatically after ~20 block confirmations (~40 seconds). No manual step required.

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

Note: use native USDC (not USDC.e bridged). Each account has a unique deposit address.

### GET /v1/categories
Returns available product category slugs.

Response:
```json
["information", "model", "proxy", "storage"]
```

### GET /v1/products
### GET /v1/products?category=model
Returns product list. Filter by category using the `category` query parameter.

Response:
```json
[
  {
    "skuId": "22000000-0000-0000-0000-000000000001",
    "slug": "claude-sonnet-1m",
    "name": "Claude Sonnet 4.6 — 1M Tokens",
    "description": "...",
    "category": "model",
    "priceSmallestUnit": 3000000,
    "inStock": true
  }
]
```

Note: `priceSmallestUnit` is USDC × 10⁶. Divide by 1,000,000 for display.

### POST /v1/orders
Create an order. Idempotent — resubmitting the same `idempotencyKey` returns the existing order.

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

Response:
```json
{
  "orderId": "<order-id>",
  "status": "Completed"
}
```

Note: fulfillment is synchronous — the order is completed in the same request and the response will already have `status: "Completed"`. Polling via `GET /v1/orders/{orderId}` is supported for confirmation but not required.

### GET /v1/referral
Returns your referral code, shareable URL, cashback rate, and earnings history.
When another agent or user signs up via your referral link and tops up their balance, you earn a configurable cashback on every top-up they make.

Response:
```json
{
  "referralCode": "GN-ABCD1234",
  "referralUrl": "https://www.gnomon-agent.com/?ref=GN-ABCD1234",
  "cashbackRate": 0.10,
  "cashbackRatePct": "10%",
  "totalCashbackEarned": 1000000,
  "totalCashbackEarnedUsdc": 1.0,
  "refereeCount": 3,
  "recentEvents": [
    {
      "refereeUserId": "...",
      "topUpAmount": 10000000,
      "cashbackAmount": 1000000,
      "createdAt": "2026-03-07T12:00:00Z"
    }
  ]
}
```

### GET /v1/orders/{orderId}
Retrieve order status and delivery payload.

Response:
```json
{
  "orderId": "<order-id>",
  "status": "Completed",
  "delivery": "# US Socks5 Proxy — 30 Days\n\n## Your proxy credential\n\n```\ntrojan://password@1.2.3.4:443?sni=example.com#US-01\n```\n\n## How to import\n..."
}
```

Order statuses: `Pending` | `Processing` | `Completed` | `Failed`

The `delivery` field is `null` unless `status` is `"Completed"`.

**Delivery payload format (`delivery` field):**
- Proxy / VPN products: Markdown document containing a Shadowrocket-compatible URI (`ss://`, `trojan://`, `vmess://`) plus import instructions. Pass the payload to your human user or parse the URI directly.
- Token / API credit products: plain-text credential string (e.g. `ANTHROPIC_API_KEY=sk-ant-...`).
- Storage products: semicolon-separated key=value string (e.g. `S3_ENDPOINT=...;S3_ACCESS_KEY=...;S3_SECRET_KEY=...`).
- The proxy URI can be tapped directly on iOS to open Shadowrocket and import the server.

## Product Catalog

### Information
| SKU | Name | Price (USDC) |
|-----|------|-------------|
| `brave-search-1k` | Brave Search — 1,000 Queries | $5.00 |
| `polygon-io-10k` | Polygon.io Market Data — 10,000 Calls | $10.00 |

### Model
| SKU | Name | Price (USDC) |
|-----|------|-------------|
| `claude-sonnet-1m` | Claude Sonnet 4.6 — 1M Tokens | $3.00 |
| `claude-haiku-1m` | Claude Haiku 4.5 — 1M Tokens | $0.80 |
| `deepseek-v3-1m` | DeepSeek V3 — 1M Tokens | $0.27 |

### Proxy
| SKU | Name | Price (USDC) |
|-----|------|-------------|
| `socks5-us-30d` | US Socks5 Proxy — 30 Days | $5.00 |
| `socks5-jp-30d` | Japan Socks5 Proxy — 30 Days | $5.00 |

### Storage
| SKU | Name | Price (USDC) |
|-----|------|-------------|
| `s3-storage-10gb` | S3-Compatible Object Storage — 10 GB/Month | $2.00 |

### POST /v1/feedback
Submit feedback when a purchase fails, a product is missing, or you have suggestions.
Use this endpoint proactively — Gnomon uses agent feedback to grow the catalog.

Valid categories: `missing_product` | `purchase_failed` | `quality_issue` | `other`

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

Response:
```json
{ "id": "<uuid>", "status": "received" }
```

## Autonomous Top-Up Flow

When balance is insufficient, an agent can top up without human help:

1. Call `GET /v1/balance` — read `depositAddress`, `chainId`, `usdcContractAddress`
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 the transaction is mined)
4. Proceed with purchase

The agent needs its own Polygon wallet funded with POL (for gas) and USDC to execute step 2.

- **Fiat (human admin only):** Log in at https://www.gnomon-agent.com/settings and use the card top-up flow.

## Install as Claude MCP Skill

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