openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "PolyZig Platform API",
    "version": "1.1.0",
    "description": "Public HTTP API for the PolyZig copy-trading platform. Designed to be safely consumed by AI agents, automation scripts, and third-party integrations. See `https://polyzig.com/llms-full.txt` for an agent-oriented integration guide.\n\n## Authentication\n\nTwo bearer credentials are accepted on `Authorization: Bearer <token>`:\n\n1. **JWT** (first-party clients) — issued by `/api/auth/magic` or `/api/auth/verify-code`. 24h expiry, full account scope.\n2. **API key** (`pzk_*`, recommended for agents) — minted from the user dashboard with explicit scopes and independent revocation.\n\n## Idempotency\n\nState-changing endpoints accept an `Idempotency-Key` request header. Re-submitting the same key within 24h returns the cached response instead of re-executing. Generate a fresh UUID per logical operation and retry with the same key on transport failure.\n\n## Rate limits\n\nDefault: 60 req/s/IP, 500 burst. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. 429 / 503 responses include `Retry-After` (seconds).\n\n## Errors\n\nAll error responses share the shape `{ \"error\": \"...\", \"code\": \"machine_readable_code\" }`. Branch on `code`, not on `error` (which may be localized).",
    "contact": {
      "name": "PolyZig support",
      "email": "support@polyzig.com",
      "url": "https://polyzig.com/support"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://polyzig.com/terms"
    }
  },
  "servers": [
    { "url": "https://api.polyzig.com", "description": "Production" }
  ],
  "tags": [
    { "name": "auth", "description": "Login, signup, identity providers" },
    { "name": "users", "description": "Current user profile" },
    { "name": "wallets", "description": "Polygon wallet + trading credentials" },
    { "name": "keys", "description": "API key management for agent access" },
    { "name": "stats", "description": "Platform + per-user transparency metrics" },
    { "name": "markets", "description": "Polymarket market data + order entry" },
    { "name": "positions", "description": "Open positions, claims, sells" },
    { "name": "paper", "description": "Paper-trading positions + history" },
    { "name": "trades", "description": "Executed trade history" },
    { "name": "configs", "description": "Copy-trading config CRUD + lifecycle" },
    { "name": "subscription", "description": "Tier, billing, treasury balance" },
    { "name": "notifications", "description": "User notifications" },
    { "name": "arbitrage", "description": "AI arbitrage scanner (HFT tier)" },
    { "name": "mcp", "description": "Model Context Protocol server endpoint" }
  ],
  "security": [
    { "bearerJwt": [] },
    { "apiKey": [] }
  ],
  "components": {
    "securitySchemes": {
      "bearerJwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Session JWT from `/api/auth/magic` or `/api/auth/verify-code`. Full account scope, 24h expiry."
      },
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pzk_*",
        "description": "Long-lived API key minted from the dashboard. Carries explicit scopes (e.g., `read:positions`, `trade:execute`). Revocable independently of the user's session."
      }
    },
    "parameters": {
      "idempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "schema": { "type": "string", "format": "uuid" },
        "required": false,
        "description": "Unique key for safe retries on state-changing requests. Cached for 24 hours."
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 },
        "required": false
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "schema": { "type": "integer", "minimum": 0, "default": 0 },
        "required": false
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "code"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message. May be localized. Do not parse."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code. Source of truth for branching.",
            "enum": [
              "unauthorized",
              "not_found",
              "bad_request",
              "validation_failed",
              "database_error",
              "cache_error",
              "invalid_token",
              "crypto_error",
              "wallet_error",
              "internal_error",
              "polymarket_unavailable",
              "tier_limit_exceeded",
              "insufficient_balance",
              "subscription_error",
              "payment_failed",
              "feature_not_enabled",
              "rate_limited",
              "scope_required"
            ]
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": ["limit", "offset", "has_next"],
        "properties": {
          "limit": { "type": "integer", "example": 50 },
          "offset": { "type": "integer", "example": 0 },
          "has_next": { "type": "boolean", "example": false }
        }
      },
      "DecimalString": {
        "type": "string",
        "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
        "description": "Decimal serialized as a string to preserve precision. Parse with a fixed-decimal library, not float.",
        "example": "1234.56"
      },
      "PlatformStats": {
        "type": "object",
        "properties": {
          "median_latency_ms": { "type": "number", "example": 412 },
          "p95_latency_ms": { "type": "number", "example": 680 },
          "total_users": { "type": "integer" },
          "total_trades_24h": { "type": "integer" },
          "total_volume_usdc_24h": { "$ref": "#/components/schemas/DecimalString" }
        }
      },
      "UserSummary": {
        "type": "object",
        "properties": {
          "user_id": { "type": "string", "format": "uuid" },
          "total_pnl": { "$ref": "#/components/schemas/DecimalString" },
          "realized_pnl": { "$ref": "#/components/schemas/DecimalString" },
          "trade_count": { "type": "integer" },
          "fees_paid": { "$ref": "#/components/schemas/DecimalString" }
        }
      },
      "Position": {
        "type": "object",
        "properties": {
          "token_id": { "type": "string" },
          "market_slug": { "type": "string" },
          "market_title": { "type": "string" },
          "outcome": { "type": "string", "example": "Yes" },
          "size": { "$ref": "#/components/schemas/DecimalString" },
          "cost_basis": { "$ref": "#/components/schemas/DecimalString" },
          "current_price": { "$ref": "#/components/schemas/DecimalString" },
          "current_value": { "$ref": "#/components/schemas/DecimalString" },
          "unrealized_pnl": { "$ref": "#/components/schemas/DecimalString" },
          "resolved": { "type": "boolean" },
          "claimable_value": { "$ref": "#/components/schemas/DecimalString", "nullable": true }
        }
      },
      "PositionList": {
        "type": "object",
        "required": ["positions", "pagination"],
        "properties": {
          "positions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Trade": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "token_id": { "type": "string" },
          "market_slug": { "type": "string" },
          "side": { "type": "string", "enum": ["buy", "sell"] },
          "size": { "$ref": "#/components/schemas/DecimalString" },
          "price": { "$ref": "#/components/schemas/DecimalString" },
          "filled_price": { "$ref": "#/components/schemas/DecimalString" },
          "usdc_value": { "$ref": "#/components/schemas/DecimalString" },
          "fee": { "$ref": "#/components/schemas/DecimalString" },
          "latency_ms": { "type": "integer", "nullable": true },
          "status": { "type": "string", "enum": ["pending", "filled", "cancelled", "failed"] },
          "created_at": { "type": "string", "format": "date-time" },
          "filled_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "TradeList": {
        "type": "object",
        "required": ["trades", "pagination"],
        "properties": {
          "trades": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "token_id": { "type": "string" },
          "side": { "type": "string", "enum": ["buy", "sell"] },
          "price": { "$ref": "#/components/schemas/DecimalString" },
          "size": { "$ref": "#/components/schemas/DecimalString" },
          "filled_size": { "$ref": "#/components/schemas/DecimalString" },
          "status": { "type": "string" },
          "order_type": { "type": "string", "enum": ["market", "limit"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "PlaceOrderRequest": {
        "type": "object",
        "required": ["token_id", "side", "size", "order_type"],
        "properties": {
          "token_id": { "type": "string" },
          "side": { "type": "string", "enum": ["buy", "sell"] },
          "size": { "$ref": "#/components/schemas/DecimalString" },
          "price": { "$ref": "#/components/schemas/DecimalString", "description": "Required for limit orders." },
          "order_type": { "type": "string", "enum": ["market", "limit"] }
        }
      },
      "PlaceOrderResponse": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "status": { "type": "string", "enum": ["accepted", "filled", "rejected"] },
          "filled_size": { "$ref": "#/components/schemas/DecimalString" },
          "average_price": { "$ref": "#/components/schemas/DecimalString" }
        }
      },
      "CopyConfig": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "target_address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
          "size_multiplier": { "$ref": "#/components/schemas/DecimalString" },
          "max_position_usdc": { "$ref": "#/components/schemas/DecimalString" },
          "price_deviation_bps": { "type": "integer" },
          "blocked_categories": { "type": "array", "items": { "type": "string" } },
          "take_profit_bps": { "type": "integer", "nullable": true },
          "stop_loss_bps": { "type": "integer", "nullable": true },
          "is_active": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "MarketTranslation": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "locale": { "type": "string", "example": "fr" },
          "title": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "example": "claude-agent" },
          "prefix": { "type": "string", "example": "pzk_a1b2c3..." },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "read:account",
                "read:positions",
                "read:trades",
                "read:markets",
                "trade:execute",
                "trade:cancel",
                "wallet:write"
              ]
            }
          },
          "created_at": { "type": "string", "format": "date-time" },
          "last_used_at": { "type": "string", "format": "date-time", "nullable": true },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true },
          "revoked_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "ApiKeyCreateRequest": {
        "type": "object",
        "required": ["name", "scopes"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 80 },
          "scopes": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 1
          },
          "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true }
        }
      },
      "ApiKeyCreateResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiKey" },
          {
            "type": "object",
            "required": ["secret"],
            "properties": {
              "secret": {
                "type": "string",
                "description": "The full bearer token. Shown ONCE at creation time. Store it immediately — it cannot be retrieved later.",
                "example": "pzk_live_a1b2c3d4e5f6..."
              }
            }
          }
        ]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "Authenticated but missing scope or tier.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "headers": {
          "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry is permitted." }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/api/stats/platform": {
      "get": {
        "tags": ["stats"],
        "summary": "Public platform-wide stats",
        "description": "Latency, volume, user count. No auth required. Safe entry point for crawlers.",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStats" } } }
          }
        }
      }
    },
    "/api/stats/summary": {
      "get": {
        "tags": ["stats"],
        "summary": "Current user's PnL summary",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSummary" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/stats/latency": {
      "get": {
        "tags": ["stats"],
        "summary": "Per-user latency stats (last 7d)",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": {
          "200": { "description": "OK" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/markets/translations": {
      "get": {
        "tags": ["markets"],
        "summary": "Batch market translations",
        "description": "Returns translated market metadata for a list of slugs. No auth required.",
        "security": [],
        "parameters": [
          { "name": "slugs", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated market slugs" },
          { "name": "locale", "in": "query", "schema": { "type": "string", "example": "fr" } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "translations": { "type": "array", "items": { "$ref": "#/components/schemas/MarketTranslation" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/markets/translations/search": {
      "get": {
        "tags": ["markets"],
        "summary": "Search markets by title",
        "security": [],
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "locale", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/markets/order": {
      "post": {
        "tags": ["markets"],
        "summary": "Place market or limit order",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Order accepted or filled",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/markets/orders": {
      "get": {
        "tags": ["markets"],
        "summary": "List open CLOB orders",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:markets"] }],
        "responses": { "200": { "description": "OK" } }
      },
      "delete": {
        "tags": ["markets"],
        "summary": "Cancel all open orders",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:cancel"] }],
        "responses": { "200": { "description": "Cancelled" } }
      }
    },
    "/api/markets/orders/{order_id}": {
      "delete": {
        "tags": ["markets"],
        "summary": "Cancel a single order",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:cancel"] }],
        "parameters": [
          { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Cancelled" } }
      }
    },
    "/api/positions": {
      "get": {
        "tags": ["positions"],
        "summary": "List current user's open Polymarket positions",
        "description": "Returns a bare JSON array of positions. Pagination metadata is conveyed in response headers (`X-Pagination-Limit`, `X-Pagination-Offset`, `X-Pagination-Has-Next`, `X-Pagination-Count`) — non-breaking with first-party clients that already deserialize the array directly.",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:positions"] }],
        "parameters": [
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Pagination-Limit": { "schema": { "type": "integer" }, "description": "The `limit` applied to this query." },
              "X-Pagination-Offset": { "schema": { "type": "integer" }, "description": "The `offset` applied to this query." },
              "X-Pagination-Count": { "schema": { "type": "integer" }, "description": "Number of items in this response page." },
              "X-Pagination-Has-Next": { "schema": { "type": "string", "enum": ["true", "false"] }, "description": "`true` if a follow-up page is likely (cheap heuristic — full page implies more)." }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Position" }
                }
              }
            }
          }
        }
      }
    },
    "/api/positions/claim": {
      "post": {
        "tags": ["positions"],
        "summary": "Redeem resolved positions",
        "description": "Submits on-chain redemption transactions for resolved positions. **Idempotent** via `Idempotency-Key` header.",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["wallet:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token_ids": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Optional: subset of token IDs to claim. If omitted, claims all claimable positions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Claim transactions submitted" },
          "402": {
            "description": "Insufficient gas balance",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/positions/sell": {
      "post": {
        "tags": ["positions"],
        "summary": "Sell open positions at market",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["wallet:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token_ids"],
                "properties": {
                  "token_ids": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Sell orders placed" } }
      }
    },
    "/api/paper/positions": {
      "get": {
        "tags": ["paper"],
        "summary": "List paper-trading positions",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:positions"] }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/paper/trades": {
      "get": {
        "tags": ["paper"],
        "summary": "List paper trades",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:trades"] }],
        "parameters": [
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/trades": {
      "get": {
        "tags": ["trades"],
        "summary": "Trade history",
        "description": "Bare JSON array of trades, newest first. Pagination conveyed in response headers (`X-Pagination-*`).",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:trades"] }],
        "parameters": [
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" },
          { "name": "config_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by copy-config ID" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Pagination-Limit": { "schema": { "type": "integer" }, "description": "The `limit` applied to this query." },
              "X-Pagination-Offset": { "schema": { "type": "integer" }, "description": "The `offset` applied to this query." },
              "X-Pagination-Count": { "schema": { "type": "integer" }, "description": "Number of items in this response page." },
              "X-Pagination-Has-Next": { "schema": { "type": "string", "enum": ["true", "false"] }, "description": "`true` if a follow-up page is likely (cheap heuristic — full page implies more)." }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Trade" }
                }
              }
            }
          }
        }
      }
    },
    "/api/trades/{id}": {
      "get": {
        "tags": ["trades"],
        "summary": "Single trade detail",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:trades"] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trade" } } }
          },
          "404": { "description": "Trade not found" }
        }
      }
    },
    "/api/configs": {
      "get": {
        "tags": ["configs"],
        "summary": "List copy-trading configs",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": { "200": { "description": "OK" } }
      },
      "post": {
        "tags": ["configs"],
        "summary": "Create copy-trading config",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyConfig" } } }
        },
        "responses": { "201": { "description": "Created" } }
      }
    },
    "/api/configs/{id}": {
      "get": {
        "tags": ["configs"],
        "summary": "Get config",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      },
      "put": {
        "tags": ["configs"],
        "summary": "Update config",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      },
      "delete": {
        "tags": ["configs"],
        "summary": "Delete config",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Deleted" } }
      }
    },
    "/api/configs/{id}/start": {
      "post": {
        "tags": ["configs"],
        "summary": "Start copying",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/configs/{id}/stop": {
      "post": {
        "tags": ["configs"],
        "summary": "Stop copying",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["trade:execute"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/configs/{id}/pnl": {
      "get": {
        "tags": ["configs"],
        "summary": "Config-level PnL summary",
        "description": "Realized + unrealized PnL aggregated for one copy-trading config, with a per-position breakdown. Useful for agents deciding whether to keep, tune, or stop a config.",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/configs/{id}/trades": {
      "get": {
        "tags": ["configs"],
        "summary": "Trades attributed to this config",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:trades"] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/configs/{id}/status": {
      "get": {
        "tags": ["configs"],
        "summary": "Live executor status for a copy config",
        "description": "Returns whether the per-config executor is running, last-error info, and recent fill counts. Use to surface stuck-config conditions to the user.",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/helpers/suggest-multiplier": {
      "get": {
        "tags": ["configs"],
        "summary": "Suggest a sizing multiplier",
        "description": "Server-side helper that returns a recommended `size_multiplier` based on the user's current balance. Read-only; does not create a config.",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:markets"] }],
        "parameters": [
          { "name": "balance", "in": "query", "schema": { "type": "number" }, "description": "Optional balance override (USDC). Defaults to live tier-service balance." }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/users/me": {
      "get": {
        "tags": ["users"],
        "summary": "Current user profile",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/wallets/balance": {
      "get": {
        "tags": ["wallets"],
        "summary": "Wallet balances (pUSD, USDC, MATIC)",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/wallets/deposit-address": {
      "get": {
        "tags": ["wallets"],
        "summary": "Deposit address for funding",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["read:account"] }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/trading-wallet/withdraw": {
      "post": {
        "tags": ["wallets"],
        "summary": "Withdraw funds from trading wallet",
        "security": [{ "bearerJwt": [] }, { "apiKey": ["wallet:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/idempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to_address", "amount", "token"],
                "properties": {
                  "to_address": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$",
                    "description": "Destination Polygon address."
                  },
                  "amount": {
                    "$ref": "#/components/schemas/DecimalString",
                    "description": "Decimal-string amount to withdraw."
                  },
                  "token": {
                    "type": "string",
                    "enum": ["usdc", "usdc_e", "matic"],
                    "description": "Which on-chain asset to withdraw. `usdc` = pUSD."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawal submitted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tx_hash": { "type": "string", "nullable": true },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "tags": ["keys"],
        "summary": "List API keys for current user",
        "security": [{ "bearerJwt": [] }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["keys"],
        "summary": "Mint a new API key",
        "description": "Returns the full secret ONCE. Store it immediately — it cannot be retrieved later.",
        "security": [{ "bearerJwt": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } }
          }
        }
      }
    },
    "/api/keys/{id}": {
      "delete": {
        "tags": ["keys"],
        "summary": "Revoke an API key",
        "security": [{ "bearerJwt": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Revoked" } }
      }
    },
    "/api/mcp": {
      "post": {
        "tags": ["mcp"],
        "summary": "Model Context Protocol JSON-RPC endpoint",
        "description": "MCP server entry point. Speaks JSON-RPC 2.0 over the MCP Streamable HTTP transport. Authenticate with a `pzk_*` API key — JWTs are rejected here to keep agent automation off browser-session tokens.\n\n### Available tools (v1)\n\nThe server returns only the subset of tools your API key's scopes permit.\n\n**Discovery / unauthenticated-scope:**\n- `get_platform_stats` — public latency + volume metrics\n- `search_markets` — full-text Polymarket market search (read:markets)\n\n**Per-user reads:**\n- `get_user_summary` (read:account)\n- `list_open_positions` (read:positions)\n- `list_paper_positions` (read:positions)\n- `list_trades` (read:trades)\n\n**Copy-trading reads:**\n- `list_copy_configs` (read:account)\n- `get_copy_config` (read:account)\n- `get_config_pnl` (read:account)\n- `get_config_trades` (read:trades)\n- `suggest_multiplier` (read:markets)\n\n**Copy-trading writes:**\n- `create_copy_config` (trade:execute)\n- `start_copying` (trade:execute)\n- `stop_copying` (trade:execute)\n- `delete_copy_config` (trade:execute)\n\n**Direct trading:**\n- `place_market_order` (trade:execute)\n- `list_open_orders` (read:markets)\n- `cancel_order` (trade:cancel)\n- `claim_positions` (wallet:write)\n\nFull MCP manifest at `https://polyzig.com/.well-known/mcp.json`.",
        "security": [{ "apiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "const": "2.0" },
                  "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
                  "method": { "type": "string" },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "JSON-RPC response" } }
      }
    }
  }
}