Example

Walk through a complete integration from setup to execution.

This section walks through a practical end-to-end flow that mirrors how an external bot or trading terminal typically integrates Polyscout.

All examples below assume:

• Base URL: https://api.polyscout.io

• You have a builder API key from Telegram /api

• You export it as POLYSCOUT_API_KEY

export POLYSCOUT_API_KEY="your_api_key"
export POLYSCOUT_API_URL="https://api.polyscout.io"

Step 1: Confirm Your Key Works

curl -sS \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  "$POLYSCOUT_API_URL/v1/me"

You should receive a response like:

{ "user": { "id": "...", "telegram_id": "...", "username": "...", "default_wallet_id": null } }

Step 2: Register a Remote Signer Wallet

This registers a wallet that Polyscout can execute against without ever receiving a private key. Your signer service must already be running and reachable at the URL you provide.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -X POST \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "owner_address": "0xYourSignerAddress",
    "url": "https://your-signer.example",
    "shared_secret": "change-me",
    "label": "polygun-user-001",
    "deploy_safe": true,
    "set_as_default": true
  }' \
  "$POLYSCOUT_API_URL/v1/wallets/remote-http"

The response returns the created wallet object. Save the wallet.id because you will use it for strategies.

Step 3: Verify the Remote Signer

Verification proves the signer actually controls the owner_address and allows the wallet to be used for execution.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -X POST \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  "$POLYSCOUT_API_URL/v1/wallets/$WALLET_ID/signer/verify"

Expected response:

{ "verified": true }

Step 4: Create a Strategy

This creates an automated strategy scoped to the wallet you registered. Once started, Polyscout will continuously monitor odds and execute entries and exits based on this configuration.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -X POST \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "wallet_id": "'"$WALLET_ID"'",
    "label": "BTC 15m odds trigger",
    "asset": "BTC",
    "timeframe": "15m",
    "trade_amount": 10,
    "odds_threshold": 0.55,
    "minutes_before_end": 5,
    "stop_loss_percent": 0.10,
    "take_profit_percent": 0.15,
    "max_executions_per_event": 1,
    "max_entry_slippage": 0.02,
    "ma_filter_enabled": true,
    "min_volatility": 0.0,
    "status": "stopped"
  }' \
  "$POLYSCOUT_API_URL/v1/strategies"

The response returns the strategy object. Save strategy.id.

Step 5: Start the Strategy

Starting the strategy switches status to active and begins the live execution loop.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -X POST \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  "$POLYSCOUT_API_URL/v1/strategies/$STRATEGY_ID/start"

Step 6: Monitor Executions

Executions are created whenever Polyscout places or settles a trade. This is what most integrations use to show activity in their UI.

curl -sS \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  "$POLYSCOUT_API_URL/v1/executions?wallet_id=$WALLET_ID&limit=25"

Step 7: Stop the Strategy

Stopping the strategy switches status to stopped and halts the execution loop for that strategy.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -X POST \
  -H "Authorization: Bearer $POLYSCOUT_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  "$POLYSCOUT_API_URL/v1/strategies/$STRATEGY_ID/stop"

Practical Notes

Remote signing is the main thing to get right. Once the signer is live and verification succeeds, everything else becomes straightforward API calls.

If your integration creates many end-user wallets, the typical pattern is:

• Create one Polyscout wallet per end user wallet you control

• Store wallet.id in your database

• Create strategies scoped to that wallet

• Use executions as your activity feed for the UI