Skip to main content

​
Wallets

PolySimulator separates trading balance into distinct wallets so that bot trading, manual UI trading, and paid sandbox experiments don’t interfere with each other. The wallet that fills your order depends on how the order was authenticated.

​
Wallets at a glance

WalletStarting balanceReset / top-upUsed by
APIPlan-dependent baseline (Free: none — read-only, Pro: 10,000,Pro+:10,000, Pro+: 25,000)Free reset; cooldown is API_RESET_COOLDOWN_DAYS (0 during the beta period, through 2026-08-31)Any request authenticated with X-API-Key
MAIN$1,000Free resets capped per 30 days (Free: 1, Pro: 4, Pro+: unlimited). Paid topup_main_reset SKU bypasses the cooldown.UI trading on polysimulator.com
SANDBOXPlan-dependent baseline (Free: 0,Pro:0, Pro: 10,000, Pro+: $25,000)Paid top-ups (topup_500, topup_2000, topup_10000) credit on top of the baselinePro-tier UI users running paid experiments
COMPETITIONVaries per eventEvent-scoped, frozen during competitionEvent entrants only
As an API user, you only need to think about the API wallet. The UI MAIN and SANDBOX wallets are for human-trader use on the website.

​
The API wallet

When you create your first key with POST /v1/keys/bootstrap, your account is seeded with your tier’s API wallet baseline (10,000onPro,10,000 on Pro, 25,000 on Pro+; Free-tier API keys are read-only and have no API wallet seeded). Every order you place via X-API-Key debits this wallet — GET /v1/account/balance always reports the API wallet balance for API-authenticated requests. 
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  https://api.polysimulator.com/v1/account/balance
# Pro tier → {"balance": "9745.20", "starting_balance": "10000.00", ...}
# Pro+ tier → {"balance": "24745.20", "starting_balance": "25000.00", ...}

​
Resetting the API wallet

You can reset the API wallet to your tier’s starting balance at any time — this also closes any open API-sourced positions. Pro keys reset to 10,000;Pro+keysresetto10,000; Pro+ keys reset to 25,000. 
curl -X POST -H "X-API-Key: $POLYSIM_API_KEY" \
  https://api.polysimulator.com/v1/account/reset-api-balance
# Pro → {"message": "API balance reset to $10,000.00",
#        "new_api_balance": "10000.00",
#        "positions_closed": 3,
#        "cooldown_days": 0}
# Pro+ → {"message": "API balance reset to $25,000.00",
#         "new_api_balance": "25000.00",
#         "positions_closed": 0,
#         "cooldown_days": 0}
The reset response carries four fields:
FieldTypeDescription
messagestringHuman-readable confirmation
new_api_balancestringThe post-reset balance (your tier baseline)
positions_closedintegerNumber of open API positions force-closed by the reset
cooldown_daysintegerDays until the next reset is allowed — equals API_RESET_COOLDOWN_DAYS (0 during the beta period)
API wallet resets are free and currently uncapped — the cooldown is gated by API_RESET_COOLDOWN_DAYS, which is 0 during the beta period (through 2026-08-31). After that a daily cooldown may apply, but resets stay included with the API tier. Use them aggressively to test new strategies from a clean baseline.

​
Scoping account reads to a wallet

The account read endpoints accept a wallet_id query parameter with three forms (case-insensitive keywords):
ValueMeaning
(omitted)Your API wallet — the default on every account read
apiYour API wallet, explicitly (includes legacy rows recorded before per-wallet attribution)
allEvery wallet you own — UI MAIN/SANDBOX/COMPETITION included
<integer id>One specific wallet you own (ids from GET /v1/me/wallets); 404 WALLET_NOT_FOUND otherwise. MAIN/API wallet ids fold in legacy rows recorded before per-wallet attribution
Supported on Positions, Trade History, Profile Analysis, Portfolio and Equity Curve. Balance is always API-wallet scoped. Any other wallet_id value returns 422 VALIDATION_FAILED. 
# Default — API wallet only
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  https://api.polysimulator.com/v1/account/positions

# Everything you own, including UI wallets
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  "https://api.polysimulator.com/v1/account/positions?wallet_id=all"
Migration note (2026-06-10): GET /v1/account/positions, GET /v1/account/history and GET /v1/account/profile-analysis previously defaulted to all wallets when wallet_id was omitted. Since 2026-06-10 they default to the API wallet, consistent with Balance/Portfolio/Equity. Pass wallet_id=all to keep the old behaviour.

​
Why the wallets are separate

The split exists so that:
  • Bots can crash without nuking your UI portfolio. A runaway loop that blows the API wallet doesn’t touch your $1,000 MAIN balance or any SANDBOX experiment.
  • The leaderboard stays clean. Only MAIN-wallet trades count toward leaderboard ranking — bot performance is tracked separately on the API beta dashboard.
  • Paid top-ups don’t mix with sacred state. Top-ups always credit SANDBOX wallets; the MAIN $1,000 is preserved as the canonical “fresh-account” baseline for any user.

​
Top-ups (paid)

Top-ups are paid Stripe purchases that credit a SANDBOX wallet for users who want extra paper-trading capital on the UI side. They do not affect the API wallet.
SKUPriceCredits
topup_500$2.99$500 to SANDBOX
topup_2000$4.99$2,000 to SANDBOX
topup_10000$9.99$10,000 to SANDBOX
topup_main_reset$2.99Resets MAIN to its seed baseline ($1,000); credits no new funds (bypasses the reset cooldown)
If you only use the API, you can ignore this entire section.

​
See also

  • Balance — GET /v1/account/balance reference
  • Portfolio — combined balance + positions snapshot
  • API keys — bootstrap and key management