HTTP Endpoints

This section lists every HTTP endpoint exposed by the Polyscout API.

All /v1/* endpoints require the Authorization: Bearer <POLYSCOUT_API_KEY> header unless explicitly noted.

Health

GET /health

Returns a basic liveness payload. This endpoint is unauthenticated.

Response:

{ "status": "ok", "timestamp": "2026-01-26T00:00:00.000Z", "service": "polyscout-api" }

Auth

GET /v1/me

Returns the authenticated builder profile.

Response:

{ "user": <User> }

Example:

curl -sS \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  "https://api.polyscout.io/v1/me"

POST /v1/api-key/rotate

Rotates the caller’s API key. The new key is returned once in the response.

Headers:

• Authorization: Bearer <POLYSCOUT_API_KEY>

• Idempotency-Key is recommended

Response:

{
  "api_key": "string",
  "api_key_prefix": "string",
  "rotated_at": "2026-01-26T00:00:00.000Z"
}

Wallets

GET /v1/wallets

Lists wallets for the authenticated builder profile.

Query parameters:

• cursor (integer, optional)

• limit (integer, optional, max 25)

Response:

{ "wallets": [<Wallet>], "next_cursor": 0 }

POST /v1/wallets/generate

Generates a new wallet and returns the private key once.

Headers:

• Idempotency-Key is recommended

Body (optional):

{
  "label": "string",
  "set_as_default": true
}

Response (201):

{ "wallet": <Wallet>, "owner_private_key": "string" }

POST /v1/wallets/import

Imports a wallet by private key. The private key is not returned.

Headers:

• Idempotency-Key is recommended

Body:

{
  "private_key": "0x...",
  "label": "string",
  "set_as_default": false
}

Response (201):

{ "wallet": <Wallet> }

POST /v1/wallets/remote-http

Creates a wallet backed by a user-hosted remote signer. No private key is stored in Polyscout.

Headers:

• Idempotency-Key is recommended

Body:

{
  "owner_address": "0x...",
  "url": "https://your-signer.example",
  "shared_secret": "string",
  "label": "string",
  "deploy_safe": true,
  "set_as_default": true
}

Response (201):

{ "wallet": <Wallet> }

GET /v1/wallets/{walletId}

Gets a wallet by id.

Response:

<Wallet>

PUT /v1/wallets/{walletId}/signer/remote-http

Configures a remote signer for an existing wallet. This sets configuration only. Verification is done separately.

Body:

{
  "url": "https://your-signer.example",
  "shared_secret": "string",
  "expected_address": null
}

Response:

<Wallet>

POST /v1/wallets/{walletId}/signer/verify

Verifies the configured signer by signing a challenge and checking the recovered address.

Headers:

• Idempotency-Key is recommended

Response:

{ "verified": true }

Strategies

GET /v1/strategies

Lists strategies for the authenticated builder profile.

Query parameters:

• wallet_id (uuid, optional)

• cursor (integer, optional)

• limit (integer, optional, max 25)

Response:

{ "strategies": [<Strategy>], "next_cursor": 0 }

POST /v1/strategies

Creates a strategy.

Headers:

• Idempotency-Key is recommended

Body:

{
  "wallet_id": "uuid",
  "label": "string",
  "asset": "BTC",
  "timeframe": "15m",
  "trade_amount": 10,
  "odds_threshold": 0.55,
  "minutes_before_end": 5,
  "stop_loss_percent": 0.1,
  "stop_loss_odds": null,
  "take_profit_percent": 0.15,
  "take_profit_odds": null,
  "max_executions_per_event": 1,
  "max_entry_slippage": 0.02,
  "ma_filter_enabled": true,
  "min_volatility": 0.0,
  "status": "stopped"
}

Response (201):

<Strategy>

GET /v1/strategies/{strategyId}

Gets a strategy by id.

Response:

<Strategy>

PATCH /v1/strategies/{strategyId}

Updates a strategy. Omitted fields remain unchanged. Some fields accept null to clear.

Response:

<Strategy>

DELETE /v1/strategies/{strategyId}

Deletes a strategy.

Response:

204 No Content

POST /v1/strategies/{strategyId}/start

Sets the strategy status to active.

Headers:

• Idempotency-Key is recommended

Response:

<Strategy>

POST /v1/strategies/{strategyId}/stop

Sets the strategy status to stopped.

Headers:

• Idempotency-Key is recommended

Response:

<Strategy>

Place Bets

GET /v1/place-bets

Lists place-bets for the authenticated builder profile.

Query parameters:

• wallet_id (uuid, optional)

• status (string, optional)

• cursor (integer, optional)

• limit (integer, optional, max 25)

Response:

{ "place_bets": [<PlaceBet>], "next_cursor": 0 }

POST /v1/place-bets

Creates a place-bet pinned to a specific event_slug.

Headers:

• Idempotency-Key is recommended

Response (201):

<PlaceBet>

GET /v1/place-bets/{placeBetId}

Gets a place-bet by id.

Response:

<PlaceBet>

PATCH /v1/place-bets/{placeBetId}

Updates a place-bet. Only allowed while status=open.

Response:

<PlaceBet>

POST /v1/place-bets/{placeBetId}/cancel

Cancels a place-bet. Only allowed while status=open.

Headers:

• Idempotency-Key is recommended

Response:

<PlaceBet>

Executions

GET /v1/executions

Lists executions for the authenticated builder profile.

Query parameters:

• wallet_id (uuid, optional)

• status (string, optional)

• cursor (integer, optional)

• limit (integer, optional, max 25)

Response:

{ "executions": [<Execution>], "next_cursor": 0 }

GET /v1/executions/{executionId}

Gets an execution by id.

Response:

<Execution>