# AgentShare — Agent-paid API - full outline (from OpenAPI)

This file is a **human/LLM-readable outline** of the same contract as `/openapi.json` (agent paths only). For machine parsing, prefer the JSON OpenAPI document.

- **OpenAPI version:** `3.1.0`
- **API version:** `1.0.0`

## API description
AI agent DeFi intelligence for Solana (Meteora DLMM briefs, DEX scout) plus marketplace price API — JSON API and MCP Streamable HTTP.

## Servers
- `https://agentshare.dev` — Production

## Security schemes
- **`ApiKeyAuth`** (`apiKey`) — API key for authenticated endpoints.
- **`X402Payment`** (`apiKey`) — x402 v2 payment payload (Base64 JSON). Alternative to X-API-Key for dual-auth routes; unpaid requests receive HTTP 402 + PAYMENT-REQUIRED.

## Operations

### `GET /api/v1/agent-capabilities`
Discover API capabilities (no auth)

Machine-readable capability description for AI agents and automated API discovery. Returns what the API does, available endpoints, data types, and common use cases.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/agent/capabilities/request`
Request a new MCP capability (Custom Request Tool)

Submit a structured capability gap when fixed MCP tools are insufficient. Does not execute or generate new code — stores a review ticket in the AgentShare admin web inbox. Auth: X-API-Key or x402. Spam gates: mandatory schema, rate limits, paid stake (see meta.billing).

**Request body:**
- `application/json` → `CapabilityRequestBody`

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/agent/commerce/quote`
Commerce quote (GET convenience)

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | yes | string | Product / offer query. |
| `query` | query | no | string | Alias for q. |
| `mode` | query | no | string | Quote mode. |
| `limit` | query | no | integer |  |
| `max_price_usd` | query | no | number | Optional budget cap (USD). |
| `currency` | query | no | string |  |

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `POST /api/v1/agent/commerce/quote`
Commerce quote (ACP / agent buyers)

Returns agentshare.price.v1 listings for Virtuals ACP deliverables. Wraps GET /api/v1/search or /api/v1/offers/best (or best-under-budget when max_price_usd set). Auth: X-API-Key header.

**Request body:**
- `application/json` → `CommerceQuoteBody`

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/agent/defi/meteora/brief`
Meteora DLMM yield/arbitrage brief (GET convenience)

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | no | string |  |
| `window` | query | no | string | Freshness window (e.g. 5m, 1h). |
| `sort_by` | query | no | string |  |
| `limit` | query | no | integer | Number of pools to return. |
| `query` | query | no | object |  |
| `filter_by` | query | no | object |  |
| `page` | query | no | integer |  |
| `page_size` | query | no | integer |  |
| `min_tvl` | query | no | object |  |
| `honor_sort` | query | no | boolean |  |
| `min_volume_5m` | query | no | object |  |
| `min_momentum` | query | no | object |  |
| `max_tvl` | query | no | object |  |
| `min_risk` | query | no | object |  |
| `max_risk` | query | no | object |  |
| `verdicts` | query | no | object |  |
| `exclude_flags` | query | no | object |  |
| `scan_pages` | query | no | object |  |
| `format` | query | no | string | Response density. |
| `fields` | query | no | object | Comma-separated fields to keep. |
| `strip_nulls` | query | no | object |  |
| `X-Brief-Source` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `POST /api/v1/agent/defi/meteora/brief`
Meteora DLMM yield/arbitrage brief (agent-ready)

Returns an AgentShare evidence-first brief for Meteora DLMM pools: verdict, risk_score, flags, citations. Freshness tiers: economy cache TTL chat 30m (default REST/MCP), A2A 60s via X-Brief-Source: a2a_paid|a2a_trial. Response meta.freshness documents tier, cache_hit, max_staleness_seconds. verdict/risk are AgentShare heuristics on Meteora metrics — not financial advice. Auth: X-API-Key OR x402 (HTTP 402 + PAYMENT-SIGNATURE). Token tip: ?format=compact and limit 3–5.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `format` | query | no | object | Set to 'compact' for abbreviated keys (see GET /api/v1/protocol). |
| `fields` | query | no | object | Comma-separated fields to keep. Prefer limit 3–5 for fewer tokens. |
| `strip_nulls` | query | no | object | Omit null/empty fields (default true when format=compact). |
| `X-Brief-Source` | header | no | object |  |

**Request body:**
- `application/json` → `MeteoraBriefBody`

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/agent/defi/meteora/pool-detail`
Meteora DLMM pool detail (GET convenience)

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `pool_address` | query | yes | string |  |
| `wallet_address` | query | no | object |  |
| `band_bps` | query | no | integer |  |
| `window` | query | no | string |  |
| `include_ohlcv` | query | no | boolean |  |
| `interval` | query | no | string |  |
| `limit` | query | no | integer |  |
| `format` | query | no | object |  |
| `fields` | query | no | object |  |
| `strip_nulls` | query | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/agent/defi/meteora/pool-detail`
Meteora DLMM pool detail v2 (identity, range_health, derived bins)

Schema agentshare.meteora.pool_detail.v2. Evidence-first single-pool detail: price_unit + base/quote mints/symbols/pair_label, range_health (0..1) or range_health_status=unavailable (never fake 0), derived active_bin_id + suggested_spot_range (±band_bps), fee signals with meta.window, ohlcv stub. OpenClaw Lab: do not render missing range_health as 0%; trust price_unit for chart scale. Precision tier: live upstream fetch every request (no response cache). Auth: X-API-Key OR x402 (HTTP 402 + PAYMENT-SIGNATURE).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `format` | query | no | object | Set to 'compact' for abbreviated keys. |
| `fields` | query | no | object | Comma-separated fields to keep. |
| `strip_nulls` | query | no | object |  |

**Request body:**
- `application/json` → `MeteoraPoolDetailBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/agent/defi/solana/brief`
Solana DEX ecosystem brief (agent-ready)

Evidence-first brief for Solana DEX protocols (Raydium, Orca, Meteora, …) using DefiLlama 24h volume and change proxies. Public read-only; x402-ready billing metadata in meta.billing. Pool-level Meteora DLMM: POST /api/v1/agent/defi/meteora/brief (requires API key).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer | Prefer 5–10 for macro scout (fewer tokens). |
| `highlights_only` | query | no | boolean | When true, return only highlighted Solana venues (Raydium, Orca, Meteora, …). |
| `format` | query | no | object | Set to 'compact' for abbreviated keys. |
| `fields` | query | no | object | Comma-separated fields to keep. |
| `strip_nulls` | query | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/agent/security/dd-brief`
Token security DD brief (GET convenience)

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | no | string |  |
| `token_address` | query | yes | string |  |
| `mode` | query | no | string |  |
| `buyer_context` | query | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/agent/security/dd-brief`
Token security DD brief (ACP)

Evidence-first token due diligence: verdict, risk_score, flags, citations. Cached 30 minutes per chain+address+mode. Auth: X-API-Key.

**Request body:**
- `application/json` → `SecurityDdBriefBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/auth/login`
Login (metadata only — API key not re-issued)

Returns account info and key prefix. Full key is only available from /auth/register.

**Request body:**
- `application/json` → `LoginBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/auth/me`
Current key + linked account

Requires X-API-Key. Returns key id, plan, and user email if linked.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/auth/register`
Sign up + receive API key once

Creates a user and a free-tier API key. Plain key is returned only in this response. When EMAIL_VERIFICATION_REQUIRED=1, the response carries an empty api_key and the user must confirm via GET /api/v1/auth/verify-email?token=...

**Request body:**
- `application/json` → `RegisterBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/auth/verify-email`
Confirm email and reveal API key (one-time)

Consume a token issued by POST /auth/register when EMAIL_VERIFICATION_REQUIRED=1. Returns the plaintext API key — called by the public /verify-email HTML page.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | query | yes | string |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/changelog`
API changelog JSON (no auth)

Same payload as ``GET /changelog.json`` at site root.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/currency/convert`
Convert Currency

Convert currency.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `amount` | query | yes | number | Amount to convert |
| `from_currency` | query | no | string | Source currency |
| `to_currency` | query | no | string | Target currency |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/currency/rates`
Get Exchange Rates

Get current exchange rates.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/dashboard/api-keys`
List Api Keys

List API keys for the authenticated user. Returns key_prefix, plan, created_at, last_used.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/dashboard/revoke-key`
Revoke Key

Revoke an API key. Only keys belonging to the authenticated user can be revoked.

**Request body:**
- `application/json` → `RevokeKeyRequest`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/dashboard/usage`
Get Usage

Current month usage for the authenticated API key.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/dex/overview`
DEX overview by 24h volume (DefiLlama)

Rank DEX protocols by 24h volume or 1d change. Optional chain filter (ethereum, bsc, base, …).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | no | object | Optional chain slug (ethereum, bsc, base, arbitrum, polygon, …). |
| `limit` | query | no | integer |  |
| `sort_by` | query | no | string | Sort key: volume (default) or change_1d (absolute 1d % move). |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/dex/top-movers`
DEX top movers by 24h volume change % (DefiLlama)

Largest absolute 1d volume change among protocols above min_volume_24h_usd.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | no | object |  |
| `limit` | query | no | integer |  |
| `min_volume_24h_usd` | query | no | object | Minimum 24h volume USD to include (default from DEX_SCOUT_MIN_VOLUME_24H_USD). |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/edge/categories`
Get Edge Categories

Get edge device categories list.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/edge/compare`
Compare Edge Devices

Compare multiple edge devices at once.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `product_ids` | query | yes | string | List product IDs, separated by commas |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/edge/recommendations`
Get Edge Recommendations

Get edge device recommendations by use case.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `use_case` | query | yes | string | Use case: openclaw, llm, homeassistant, gaming, server |
| `budget` | query | no | object | Budget (USD) |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/edge/search`
Search Edge Devices

Search edge devices with specific filters.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | yes | string | Search keyword |
| `category` | query | no | object | Filter by category |
| `subcategory` | query | no | object | Filter by subcategory |
| `min_price` | query | no | object | Minimum price (USD) |
| `max_price` | query | no | object | Maximum price (USD) |
| `brand` | query | no | object | Filter by brand |
| `in_stock` | query | no | boolean | Only in-stock products |
| `sort_by` | query | no | string | price_asc, price_desc, name_asc, newest |
| `limit` | query | no | integer |  |
| `currency` | query | no | string | Currency (USD, VND, EUR, GBP, JPY) |
| `fields` | query | no | object | Fields to return |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/edge/specs/{product_id}`
Get Edge Device Specs

Get detailed specs of an edge device.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `product_id` | path | yes | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/examples`
REST/MCP code examples (no auth)

Returns curl, Python (httpx), and JavaScript (fetch) snippets for common calls. Intended for agent onboarding — fetch before guessing URL shapes. Use ?template=managed-agent for Gemini Managed Agents MCP JSON.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `template` | query | no | object | managed-agent — MCP config JSON for Gemini Managed Agents / Antigravity |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/health`
Liveness check (no auth, no DB)

Process is up. Does not query the database or external services — suitable for load balancers and frequent probes. Response should be sub-50ms under normal load.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/integrations/aliexpress/affiliate/product-detail`
AliExpress affiliate product detail by ID (Open Platform)

Returns rich product data from AliExpress IOP ``aliexpress.affiliate.productdetail.get`` (images, title, prices, shop, affiliate URL). Requires server-side Open Platform app key and OAuth session; use ``product_ids`` as AliExpress product ID(s), comma-separated (from item URL). Counts toward API key credits like GET /api/v1/products/{id}. On success, appends price snapshot(s) to ``prices`` via a background task (after response is sent).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `product_ids` | query | yes | string | AliExpress product ID(s), comma-separated, e.g. 1005001234567890 |
| `include_raw` | query | no | boolean | If true, include raw IOP payload under data.raw_iop (larger response; for debugging). |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/internal/registry-health`
Registry Health Cron

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Cron-Secret` | header | no | string |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/lab/meteora/pulse`
Lab Meteora pulse snapshot (lab_pulse.v1)

Internal OpenClaw Lab pipe: slim top-N Meteora brief as `agentshare.meteora.lab_pulse.v1` for cron → volume snapshot. Auth: X-API-Key + lab gate (X-AgentShare-Lab token and/or plan/prefix allowlist). Skips free-tier per-second/per-minute limits; usage still logged. Server cache 60–120s. No social/LLM narrative. Plan: agentshare-openclaw-lab/docs/METEORA_LAB_AGENTSHARE_PULSE_PLAN.md

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `window` | query | no | string | Metric window (aligned with meteora_brief). |
| `sort_by` | query | no | string | Sort: fee_tvl_ratio \| fee \| volume \| apr \| tvl. |
| `limit` | query | no | integer | Top-N pools (max 25). |
| `kind` | query | no | string | Brief kind filter. |
| `bypass_cache` | query | no | boolean | If true, skip server pulse cache (debug only). |
| `X-AgentShare-Lab` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/mcp/stats/{mcp_id}`
Mcp Listing Stats

Outbound open analytics for one MCP Hub listing (owner stickiness pulse).

Auth (any):
- Query `token` = submission_token from submit response / status page URL
- HttpOnly cookie set by the owner status page
- Header `X-API-Key` when the listing was submitted with that key (or same user)

Agents: start with ``data.summary_line``, then ``opens_by_audience`` /
``opens_by_target`` / ``last_open_at`` / ``daily``. Use ``?days=7`` for a weekly check-in.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `mcp_id` | path | yes | integer |  |
| `token` | query | no | object | Submission bookmark token (same as /registry/status/{token}) |
| `days` | query | no | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/meta`
Discover API capabilities (no auth)

Call first to learn what this API offers. No API key needed. Returns endpoints, features, sources (aliexpress, accesstrade), and auth. Primary scope: agent-paid API rails (dual-auth, discovery, MCP). Secondary: commerce product scope (GET /coverage) and Solana/Meteora DeFi demos.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/objective-trust/objective`
Post Objective

Free. Stores weights for this API key. Does not store the sentence.

**Request body:**
- `application/json` → `ObjectiveBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/objective-trust/outcome`
Post Outcome

Free. Records this key's result for a recommendation it received.

**Request body:**
- `application/json` → `OutcomeBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/objective-trust/rank`
Post Rank

API key or x402 at $0.005. Caller pays the chosen MCP itself.

**Request body:**
- `application/json` → `RankBody`

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/offers/best`
Get cheapest offer for a product

Call when user asks 'where to buy X cheapest?' or 'best deal for X'. Returns single lowest-price offer. Use include_analysis for verdict/recommendation.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | yes | string | Search query. |
| `query` | query | no | string | Alias for q. |
| `include_analysis` | query | no | boolean | Add deal analysis (verdict, recommendation) |
| `fields` | query | no | object | Comma-separated fields to return. E.g. name,price,url |
| `simple` | query | no | boolean | Minimal field set for embedded clients. Ignored if `fields` is set. |
| `currency` | query | no | string | Output currency (VND, USD). |

**Responses:**
- `200` — Either a best offer (`status: ok`) or structured no-data (`status: no_data`) when nothing matches.
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/offers/best-under-budget`
Get best offer within budget

Call when user says 'best X under Y'. `max_price` uses the same unit as `currency` (VND or USD). Returns best_offer or null if none fits.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | no | object | Search query |
| `query` | query | no | object | Alias for q (agent clients) |
| `max_price` | query | yes | number | Maximum budget in the same unit as the currency parameter (VND or USD) |
| `include_analysis` | query | no | boolean | Add deal analysis |
| `fields` | query | no | object | Comma-separated fields to return |
| `simple` | query | no | boolean | Minimal field set for embedded clients. Ignored if `fields` is set. |
| `currency` | query | no | string | Output currency (VND, USD) |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/openplatform/aliexpress/callback`
Aliexpress Oauth Callback

AliExpress redirects here after user authorization.
Register this full URL (with production host) in App Console Callback URL.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `code` | query | no | object |  |
| `state` | query | no | object |  |
| `error` | query | no | object |  |
| `error_description` | query | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/openplatform/aliexpress/oauth/prepare`
Aliexpress Oauth Prepare

Build authorize URL with fresh CSRF ``state``. Requires ``X-Admin-Key``.
Set ``ALIEXPRESS_OPEN_STRICT_OAUTH_STATE=true`` and always start from this endpoint in production.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Admin-Key` | header | no | object |  |
| `authorization` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/products/submit`
Submit a marketplace product URL (community)

Alpha: suggest a product listing page for catalog coverage. Rate-limited per IP; higher limits with a valid X-API-Key. Does not crawl immediately — submissions are queued for review.

**Request body:**
- `application/json` → `ProductSubmitRequest`

**Responses:**
- `200` — Successful Response
- `400` — Invalid URL or host not allowed
- `422` — Validation Error
- `429` — Rate limit exceeded
- `503` — Product submissions disabled

### `GET /api/v1/products/{product_id}`
Get product details and prices by ID

Call when user has a product ID from search and wants full details. Use include_analysis for verdict/recommendation.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `product_id` | path | yes | integer |  |
| `include_analysis` | query | no | boolean | Add deal analysis (verdict, recommendation) |
| `source` | query | no | object | Optional Accesstrade/marketplace hint for live rows (domain or slug); optional |
| `fields` | query | no | object | Comma-separated fields to return |
| `simple` | query | no | boolean | Minimal field set for embedded clients. Ignored if `fields` is set. |
| `currency` | query | no | string | Output currency (VND, USD) |

**Responses:**
- `200` — Successful Response
- `404` — Product not found
- `422` — Validation Error

### `GET /api/v1/products/{product_id}/price-history`
Get price history for a product

Call when user asks about price trends or history. Use fields to reduce token.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `product_id` | path | yes | integer |  |
| `limit` | query | no | integer | Max history entries |
| `fields` | query | no | object | Comma-separated fields to return |
| `simple` | query | no | boolean | Minimal field set for embedded clients. Ignored if `fields` is set. |
| `currency` | query | no | string | Output currency (VND, USD) |

**Responses:**
- `200` — Successful Response
- `404` — Product not found
- `422` — Validation Error

### `GET /api/v1/protocol`
Protocol-lite contract (no auth)

Stable, machine-readable contract for SDK generators and autonomous agents.
Does not grant permissions — describes envelopes, error codes, and AX fields.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/public/beacon-beta`
Beacon Beta Signup

Join the Bot Beacon beta waitlist (no auth).

**Request body:**
- `application/json` → `BeaconBetaSignupIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/public/bot-traffic/stats`
Public Bot Traffic Stats

Sanitized rolling-window metrics for the public dashboard.
Exposes totals, intents, clients, and map points only — no IPs, API keys,
authenticated-agent counts, or good/suspicious/malicious mix.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/public/data-quality`
Public Data Quality

Rolling hit-rate and sample sizes from stored demand signals (no API key).
Per-response freshness and ``data_status`` still come from authenticated product endpoints.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/public/demand-summary`
Demand Summary

Public lightweight demand snapshot for dashboard widgets.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/public/live-feed`
Live Global Feed

Public sanitized activity feed.
Never includes raw queries, IPs, API keys, or user identifiers.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/public/mcp-registry/summary`
Mcp Registry Summary

Compact verified listings for agent consumption. Descriptions are truncated;
use HTML /registry or GET /api/v1/registry/entries for full text.

``q`` filters the list. When it matches nothing, ``request_missing`` tells
the agent how to POST a capability ticket.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | no | object | Search verified name, description, or tags. Empty match adds request_missing. |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/public/mcp-registry/trends`
Mcp Registry Trends

Phase C teaser: machine-readable top MCPs for agents (human + MCP-client engagement).

Ranked by human + MCP-client engagement. Aggregated counts only — no referrers/IPs.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `days` | query | no | integer |  |
| `limit` | query | no | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/range-guard/brief`
Range Guard Brief

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Init-Data` | header | no | object |  |

**Request body:**
- `application/json` → `BriefBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/range-guard/config`
Range Guard Config

Public boot config for Mini App (no secrets).

**Responses:**
- `200` — Successful Response

### `GET /api/v1/range-guard/me`
Range Guard Me

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Init-Data` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/range-guard/stars/invoice`
Range Guard Stars Invoice

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Init-Data` | header | no | object |  |

**Request body:**
- `application/json` → `InvoiceBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/range-guard/telegram/webhook`
Range Guard Telegram Webhook

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Bot-Api-Secret-Token` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/range-guard/wallet`
Range Guard Wallet

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Init-Data` | header | no | object |  |

**Request body:**
- `application/json` → `WalletBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/range-guard/watches`
Range Guard Add Watch

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Telegram-Init-Data` | header | no | object |  |

**Request body:**
- `application/json` → `WatchBody`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `DELETE /api/v1/range-guard/watches/{watch_id}`
Range Guard Delete Watch

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `watch_id` | path | yes | integer |  |
| `init_data` | query | no | object |  |
| `X-Telegram-Init-Data` | header | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/agent-key`
Mint Registry Agent Key

Mint a short-lived scoped API key for MCP registry submission.

Auth:
- valid full API key, OR
- successful x402 payment on this endpoint

**Request body:**
- `application/json` → `object`

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.

### `GET /api/v1/registry/directory/health`
Read Registry Directory Health

Stored health for one verified listing. Does not probe the MCP URL.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `record_id` | query | no | object |  |
| `mcp_url` | query | no | object |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/registry/directory/search`
Search Registry Directory

Agent search: verified listings, Featured first. Database read only.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `keyword` | query | yes | string |  |
| `category` | query | no | object |  |
| `limit` | query | no | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/registry/entries`
List Registry Entries

List verified registry entries. Agents should prefer this over HTML.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `category` | query | no | object | Slug, e.g. data_commerce |
| `q` | query | no | object | Search name/description |
| `sort` | query | no | string | new \| popular |
| `limit` | query | no | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/registry/feature/packs`
List Featured Packs

Featured pack catalog (no auth). Same prices for humans and agents.

Buy: POST /api/v1/registry/feature/{week|month|year} with JSON {"token":"…"}
and dual-auth (X-API-Key / Bearer or x402).

**Responses:**
- `200` — Successful Response

### `POST /api/v1/registry/feature/{pack}`
Purchase Registry Featured

Buy or renew MCP Hub Featured placement (dual-auth for humans and agents).

Packs: ``week`` ($3 / 7d), ``month`` ($9 / 30d), ``year`` ($49 / 365d).
Auth: valid API key **or** x402 settle on this path + JSON ``token`` (owner secret).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `pack` | path | yes | string |  |

**Request body:**
- `application/json` → `RegistryFeatureIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/registry/owner`
Registry Owner By Header

Same payload as the status URL, with the secret in X-Registry-Token instead of the path.

**Responses:**
- `200` — Successful Response

### `PUT /api/v1/registry/owner`
Put Registry Owner

PUT by header X-Registry-Token. The secret is not part of the URL.

**Request body:**
- `application/json` → `RegistrySubmitIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `PATCH /api/v1/registry/owner`
Patch Registry Owner

PATCH by header X-Registry-Token. The secret is not part of the URL.

**Request body:**
- `application/json` → `RegistryOwnerPatchIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/owner/revoke`
Revoke Registry Owner Link Header

Revoke using header X-Registry-Token.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/registry/owner/rotate`
Rotate Registry Owner Link Header

Rotate using header X-Registry-Token.

**Responses:**
- `200` — Successful Response

### `GET /api/v1/registry/status/{token}`
Registry Submission Status

Poll outcome and current listing fields. Token is the owner secret from submit.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | path | yes | string |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `PUT /api/v1/registry/status/{token}`
Put Registry Listing

Owner full replace of listing metadata (script / agent one-shot).

Auth: submission token in the path, or header X-Registry-Token. No API key.
Text edits stay live. Changing a public URL returns a verified listing to pending_review.
Rejected listings return to pending_review.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | path | yes | string |  |

**Request body:**
- `application/json` → `RegistrySubmitIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `PATCH /api/v1/registry/status/{token}`
Patch Registry Listing

Owner partial update. Omitted JSON keys are left unchanged.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | path | yes | string |  |

**Request body:**
- `application/json` → `RegistryOwnerPatchIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/status/{token}/revoke`
Revoke Registry Owner Link

Disable the owner link until an admin issues a new one.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | path | yes | string |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/status/{token}/rotate`
Rotate Registry Owner Link

Replace the owner bearer token. The previous bookmark stops working.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `token` | path | yes | string |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/submit`
Submit Registry Entry

Submit a new listing (metadata only). Status pending_review until admin approves.

**Request body:**
- `application/json` → `RegistrySubmitIn`

**Responses:**
- `200` — Successful Response
- `400` — Invalid payload or category
- `422` — Validation Error
- `429` — Submission rate limit exceeded

### `GET /api/v1/registry/suggest-tags`
Suggest Registry Tags Get

GET alias for agents that prefer query params over JSON body.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | query | yes | string |  |
| `description` | query | no | string |  |
| `category` | query | no | object |  |
| `tags` | query | no | object |  |
| `github_url` | query | no | object |  |
| `website_url` | query | no | object |  |
| `mcp_url` | query | no | object |  |
| `enrich_github` | query | no | boolean |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/registry/suggest-tags`
Suggest Registry Tags

Suggest comma-separated tags and GEO hints from the submitter's own MCP metadata.

No auth required. Tags are derived from name, description, URLs, and optional
GitHub repo metadata — not from a fixed DeFi/blockchain rule engine.

**Request body:**
- `application/json` → `RegistrySuggestTagsIn`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/search`
Search product prices (multi-source, AliExpress-forward)

Call when user asks to compare prices, search products, or find deals. Returns products with prices from connected sources (see GET /coverage and GET /api/v1/meta). Empty result set returns HTTP 200 with `status: no_data` and `reason` `pending_crawl` or `out_of_coverage` (see GET /coverage). Use fields to reduce token (e.g. name,price,url).

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `q` | query | yes | string | Search keyword (product name, brand, category). |
| `query` | query | no | string | Alias for q (agent clients). |
| `limit` | query | no | integer | Max results to return. |
| `fields` | query | no | object | Comma-separated fields to return. E.g. name,price,url. Omit for full response. |
| `simple` | query | no | boolean | If true, return a minimal field set for embedded/low-bandwidth clients. Ignored if `fields` is set. |
| `currency` | query | no | string | Output currency (VND, USD). |
| `source` | query | no | object | Optional marketplace/source slug filter (deployment-specific; e.g. accesstrade, aliexpress) |
| `include_live_at` | query | no | boolean | Merge Accesstrade datafeed search when API key configured |

**Responses:**
- `200` — Successful Response
- `402` — Payment Required (x402 v2). Base64-decode PAYMENT-REQUIRED header, sign the single exact row (Base mainnet EIP-712 name 'USD Coin' version '2'), retry with PAYMENT-SIGNATURE. Alternatively send X-API-Key to use quota plans.
- `422` — Validation Error

### `GET /api/v1/webhooks`
List Webhooks

List all webhooks for the current API key.

**Responses:**
- `200` — Successful Response

### `POST /api/v1/webhooks/register`
Register Webhook

Register a new webhook for price alerts.

**Request body:**
- `application/json` → `WebhookCreate`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `POST /api/v1/webhooks/test`
Test Webhook

Send a test webhook payload.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `url` | query | yes | string | Webhook URL to test |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `PATCH /api/v1/webhooks/{webhook_id}`
Update Webhook

Update a webhook.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | yes | integer |  |

**Request body:**
- `application/json` → `WebhookUpdate`

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `DELETE /api/v1/webhooks/{webhook_id}`
Unregister Webhook

Unregister a webhook.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | yes | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /api/v1/webhooks/{webhook_id}/deliveries`
Get Webhook Deliveries

Get delivery history for a webhook.

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | yes | integer |  |
| `limit` | query | no | integer |  |

**Responses:**
- `200` — Successful Response
- `422` — Validation Error

### `GET /coverage`
Coverage Spec

Data coverage + DeFi positioning — honesty for humans and agents.

- Browsers (Accept: text/html preferred): HTML page
- Agents / curl / ``?format=json`` / default ``*/*``: JSON
  (commerce categories + ``defi_intelligence``)

**Responses:**
- `200` — Successful Response

## Component schemas

Names below map to `$ref` in OpenAPI; full field trees live in `/openapi.json`.

- **`ApiKeyInfo`** — API key info for listing (no raw key).; type `object`; fields: `created_at, id, key_prefix, last_used_at, plan_type, status`
- **`ApiKeysResponse`** — type `object`; fields: `keys`
- **`BeaconBetaSignupIn`** — type `object`; fields: `email, source, utm_campaign, utm_medium, utm_source, website`
- **`BestOfferData`** — type `object`; fields: `analysis, best_offer, product, reasons, summary`
- **`BestOfferItem`** — type `object`; fields: `affiliate_url, availability, comparison, crawled_at, data_age_seconds, freshness_status, original_price, price, source, url`
- **`BestOfferMeta`** — type `object`; fields: `accesstrade_candidate, accesstrade_degraded, accesstrade_negative_block, accesstrade_skipped_reason, cache_hit, coverage_tier, credit_balance, data_age_seconds, data_status, freshness_status, last_updated, query, remaining_requests, timestamp, trust_hit_rate, trust_sample_size, trust_window_days`
- **`BestOfferResponse`** — type `object`; fields: `data, meta, status`
- **`BestUnderBudgetData`** — type `object`; fields: `analysis, best_offer, budget, query`
- **`BestUnderBudgetMeta`** — type `object`; fields: `budget, coverage_tier, credit_balance, data_age_seconds, data_status, freshness_status, last_updated, query, remaining_requests, timestamp, trust_hit_rate, trust_sample_size, trust_window_days`
- **`BestUnderBudgetOfferItem`** — type `object`; fields: `comparison, crawled_at, freshness_status, name, price, product_id, source, url`
- **`BestUnderBudgetResponse`** — type `object`; fields: `data, meta, status`
- **`Body_admin_capability_set_status_admin_capability_requests__req_id__status_post`** — type `object`; fields: `admin_note, status`
- **`Body_admin_registry_edit_admin_registry__entry_id__edit_post`** — type `object`; fields: `category, description, github_url, mcp_url, name, tags, website_url`
- **`Body_admin_registry_reject_admin_registry__entry_id__reject_post`** — type `object`; fields: `rejection_reason`
- **`Body_create_key_from_dashboard_admin_create_key_post`** — type `object`; fields: `agent_name, credit_balance, monthly_request_limit`
- **`Body_create_paypal_order_payment_create_paypal_order_post`** — type `object`; fields: `plan_type`
- **`Body_create_vnpay_order_payment_create_vnpay_order_post`** — type `object`; fields: `plan_type`
- **`Body_login_admin_login_post`** — type `object`; fields: `password, username`
- **`Body_patch_key_monthly_cap_admin_patch_key_monthly__key_id__post`** — type `object`; fields: `monthly_request_limit`
- **`Body_registry_owner_edit_cookie_registry_owner_post`** — type `object`; fields: `category, contact_info, description, github_url, mcp_url, name, tags, website_url`
- **`Body_registry_owner_edit_form_registry_status__token__post`** — type `object`; fields: `category, contact_info, description, github_url, mcp_url, name, tags, website_url`
- **`Body_registry_submit_form_registry_post`** — type `object`; fields: `category, contact_info, description, github_url, mcp_url, name, tags, website_url`
- **`BriefBody`** — type `object`; fields: `init_data, pool_address`
- **`CandidateBody`** — type `object`; fields: `id, mcp_url, quoted_usd`
- **`CapabilityRequestBody`** — type `object`; fields: `budget_usd, capability, contact_hint, desired_input, desired_output, nearest_existing_tool, why_insufficient`
- **`CommerceQuoteBody`** — type `object`; fields: `currency, limit, max_price_usd, mode, query`
- **`CreateKeyBody`** — type `object`; fields: `agent_name, credit_balance, expires_at, monthly_request_limit, plan_type`
- **`DealAnalysis`** — type `object`; fields: `price_trend, recommendation, stats, verdict`
- **`HTTPValidationError`** — type `object`; fields: `detail`
- **`HealthData`** — type `object`; fields: `authenticated, database, service, timestamp, version`
- **`HealthResponse`** — type `object`; fields: `data, meta, status`
- **`InvoiceBody`** — type `object`; fields: `init_data`
- **`LoginBody`** — type `object`; fields: `email, password`
- **`MetaAuth`** — type `object`; fields: `header, type`
- **`MetaData`** — type `object`; fields: `auth, description, endpoints, features, service, sources, version`
- **`MetaEndpoints`** — type `object`; fields: `agent_capabilities, auth_me, auth_register, best_offer, best_under_budget, coverage, docs, health, meta, paypal_order_api, products, products_submit, public_data_quality, request_capability, search`
- **`MetaResponse`** — type `object`; fields: `data, meta, status`
- **`MetaTimestamp`** — Common meta with timestamp.; type `object`; fields: `timestamp`
- **`MeteoraBriefBody`** — type `object`; fields: `exclude_flags, filter_by, honor_sort, kind, limit, max_risk, max_tvl, min_momentum, min_risk, min_tvl, min_volume_5m, page, page_size, query, scan_pages, sort_by, verdicts, window`
- **`MeteoraPoolDetailBody`** — type `object`; fields: `band_bps, include_ohlcv, interval, limit, pool_address, wallet_address, window`
- **`ObjectiveBody`** — type `object`; fields: `text`
- **`OutcomeBody`** — type `object`; fields: `candidate_id, cost_usd, latency_ms, recommendation_id, success`
- **`PayPalOrderApiBody`** — JSON body for API clients (requires X-API-Key).; type `object`; fields: `plan_type`
- **`PriceComparison`** — Contextual metadata: where this price sits in the result set.; type `object`; fields: `highest_in_result, lowest_in_result, position`
- **`PriceHistoryData`** — type `object`; fields: `price_history, product_id, product_name`
- **`PriceHistoryItem`** — type `object`; fields: `availability, crawled_at, currency, data_age_seconds, discount_percent, freshness_status, original_price, price, product_url, source`
- **`PriceHistoryMeta`** — type `object`; fields: `credit_balance, currency, data_age_seconds, freshness_status, last_updated, limit, remaining_requests, timestamp, total`
- **`PriceHistoryResponse`** — type `object`; fields: `data, meta, status`
- **`PriceItem`** — type `object`; fields: `affiliate_url, availability, comparison, crawled_at, data_age_seconds, freshness_status, original_price, price, source, url`
- **`ProductDetail`** — type `object`; fields: `brand, category, created_at, description, id, image_url, name, source_id, specifications, updated_at`
- **`ProductDetailData`** — type `object`; fields: `analysis, prices, product`
- **`ProductDetailMeta`** — type `object`; fields: `credit_balance, data_age_seconds, freshness_status, last_updated, remaining_requests, timestamp`
- **`ProductDetailResponse`** — type `object`; fields: `data, meta, status`
- **`ProductSubmitData`** — type `object`; fields: `duplicate, id, message`
- **`ProductSubmitRequest`** — type `object`; fields: `notes, url`
- **`ProductSubmitResponse`** — type `object`; fields: `data, meta, status`
- **`ProductSummary`** — type `object`; fields: `brand, id, image_url, name`
- **`RankBody`** — type `object`; fields: `candidates, policy_id, task`
- **`RegisterBody`** — type `object`; fields: `email, password`
- **`RegistryFeatureIn`** — Owner secret from submit / status URL — required for humans and agents.; type `object`; fields: `token`
- **`RegistryOwnerPatchIn`** — Sparse owner update — omitted fields stay as stored.; type `object`; fields: `category, contact_info, description, github_url, mcp_url, name, tags, website_url`
- **`RegistrySubmitIn`** — type `object`; fields: `category, contact_info, description, github_url, mcp_url, name, tags, website_url`
- **`RegistrySuggestTagsIn`** — type `object`; fields: `category, description, enrich_github, github_url, mcp_url, name, tags, website_url`
- **`RevokeKeyRequest`** — type `object`; fields: `key_id`
- **`SearchMeta`** — type `object`; fields: `accesstrade_live, cache_hit, coverage_tier, credit_balance, data_age_seconds, data_status, freshness_status, last_updated, limit, query, remaining_requests, source_filter, timestamp, total, trust_hit_rate, trust_sample_size, trust_window_days`
- **`SearchProductItem`** — type `object`; fields: `accesstrade_live, brand, category, id, image_url, name, prices, source_id`
- **`SearchResponse`** — type `object`; fields: `data, meta, status`
- **`SecurityDdBriefBody`** — type `object`; fields: `buyer_context, chain, mode, token_address`
- **`TopupBody`** — type `object`; fields: `credits`
- **`UsageResponse`** — type `object`; fields: `api_key_id, plan_type, quota, remaining, used_this_month`
- **`ValidationError`** — type `object`; fields: `ctx, input, loc, msg, type`
- **`WalletBody`** — type `object`; fields: `init_data, pool_address, wallet`
- **`WatchBody`** — type `object`; fields: `init_data, pool_address, wallet`
- **`WebhookConditions`** — type `object`; fields: `back_in_stock, category, discount_percent_above, price_above, price_below, price_change_percent, product_id, product_name`
- **`WebhookCreate`** — type `object`; fields: `conditions, description, url`
- **`WebhookUpdate`** — type `object`; fields: `conditions, description, is_active, url`