API Access

Learn how to connect to the Polyscout HTTP API, what headers are required, and the conventions used across all endpoints.

Base URL and Versioning

The Polyscout API is available at the following base URL:

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.

Content-Type: application/json

Authentication Header

All /v1/* endpoints require an API key passed using the standard Authorization header.

Authorization: Bearer <POLYSCOUT_USER_API_KEY>

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.

x-request-id: <your-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.

Idempotency-Key: <unique-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.

{
  "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.