Skip to main content

​
Authentication

All API v1 endpoints require an API key passed via the X-API-Key HTTP header. 
curl -H "X-API-Key: ps_live_abc123..." \
     https://api.polysimulator.com/v1/markets

​
Key Format

Keys follow a predictable pattern for easy identification: 
ps_live_<64 random hex chars>
Example: ps_live_kJ9mNx2pQrStUvWxYz01Ab3CdEfGhI4j Each key has a visible prefix (first 16 chars) used for identification without exposing the full key:
Value
Full keyps_live_kJ9mNx2pQrStUvWxYz01Ab3CdEfGhI4j
Prefixps_live_kJ9mNx2p

​
How It Works

When you send a request:
  1. Your API key is SHA-256 hashed and looked up in the database
  2. The key’s is_active and expires_at fields are validated
  3. Rate limits are enforced based on your key’s tier
  4. The associated user account is loaded for trading operations

​
Permissions

Keys support granular permissions:
PermissionGrants Access To
readMarket data, prices, balance, positions, order history, key listing
tradePlace orders, cancel orders, create/revoke API keys
A key with only read permission cannot place trades. Create a key with ["read", "trade"] permissions for bot usage.

​
Security Best Practices

Never hardcode API keys in source code. Use environment variables or a secrets manager.
export POLYSIM_API_KEY="ps_live_kJ9mNx2p..."

import os
api_key = os.environ["POLYSIM_API_KEY"]
Set expires_at when creating keys for short-lived deployments. Expired keys automatically stop working — no manual cleanup needed.
Create separate keys for different bots:
  • Data-only bot: ["read"] permission
  • Trading bot: ["read", "trade"] permission
Create a new key, update your bot, then revoke the old key:
# 1. Create new key
curl -X POST -H "X-API-Key: $OLD_KEY" \
  https://api.polysimulator.com/v1/keys \
  -d '{"name": "bot-v2", "permissions": ["read", "trade"]}'

# 2. Update your bot's environment variable

# 3. Revoke old key
curl -X DELETE -H "X-API-Key: $NEW_KEY" \
  https://api.polysimulator.com/v1/keys/OLD_KEY_ID
The system enforces a limit of 5 active keys per user account. Revoke unused keys to free up slots.

​
Error Responses

Status CodeMeaning
401 UnauthorizedInvalid, expired, or deactivated API key
403 ForbiddenKey lacks required permission for the endpoint
{
  "detail": "Invalid or expired API key"
}

​
Next Steps