# API Access ## Base URL and Versioning The Polyscout API is available at the following base URL: ```json https://api.polyscout.io ``` All API endpoints are served under versioned paths. The current version is `/v1`. All requests and responses use JSON and must include the appropriate `Content-Type` header when a body is present. ```http Content-Type: application/json ``` ## Authentication Header All `/v1/*` endpoints require an API key passed using the standard `Authorization` header. ```json Authorization: Bearer ``` API keys are issued per user and can be generated through the Polyscout Telegram bot using the `/api` command. Each key is tied to a specific Polyscout user account and controls access to that user’s wallets, strategies, and executions. If the header is missing or the key is invalid, the API returns a `401 UNAUTHORIZED` response. ## Request IDs Requests may optionally include a request identifier to help with tracing and debugging. ```python x-request-id: ``` If this header is not provided, Polyscout automatically generates one. Every response includes an `x-request-id` header so requests can be correlated in logs. ## Idempotency For POST requests that create or modify state, Polyscout supports idempotency to safely handle retries. Clients may include an `Idempotency-Key` header with a unique value per logical request. ```json Idempotency-Key: ``` If the same request is retried with the same idempotency key, Polyscout returns the original response. If the same key is reused with a different payload, the API returns a `409 IDEMPOTENCY_KEY_REUSED` error. If a request with the same idempotency key is still being processed, the API returns `409 IDEMPOTENCY_IN_PROGRESS` and includes a `Retry-After` header indicating when to retry. ## Pagination List endpoints support offset-based pagination using `cursor` and `limit` query parameters. The `cursor` parameter is a zero-based offset. The `limit` parameter controls page size, with a maximum of 25 items per request. Responses include a `next_cursor` field when additional results are available. When `next_cursor` is `null`, there are no more results. ## Rate Limiting Authenticated endpoints apply rate limits on a per-user and per-IP basis. Rate limit information is returned via standard headers: * `x-ratelimit-limit` indicates the maximum burst size * `x-ratelimit-remaining` shows how many requests remain in the current window * `x-ratelimit-reset` indicates when the limit will reset If a client exceeds the rate limit, the API returns `429 RATE_LIMITED` and includes a `Retry-After` header specifying how long to wait before retrying. ## Error Format All errors are returned in a consistent JSON structure. ```json { "error": { "code": "BAD_REQUEST", "message": "Missing or invalid trade_amount", "details": { "optional": "context" } } } ``` Common error codes include `UNAUTHORIZED`, `FORBIDDEN`, `BAD_REQUEST`, `NOT_FOUND`, `RATE_LIMITED`, and `INTERNAL`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.polyscout.io/developers/api-access.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.