Data Model

Understand the core data models used by the Polyscout API. All schemas are returned as JSON objects and follow consistent conventions across endpoints.

All UUIDs are represented as strings in canonical UUID format. Addresses are EVM hex strings.

User

Represents the builder profile associated with the API key.

Field	Type	Description
id	uuid	Polyscout user id
telegram_id	string | null	Telegram user id
username	string | null	Telegram username
default_wallet_id	uuid | null	Default wallet id

Wallet

Represents a trading wallet registered under a builder profile. A wallet may be locally managed or backed by a remote signer.

Field	Type	Description
id	uuid	Wallet id
user_id	uuid	Owning user id
label	string	Human-readable label
safe_address	string	Polygon address of the Safe wallet
owner_address	string	EOA owner address
is_primary	boolean	True if this is the default wallet
signer_type	local_private_key | remote_http	Wallet signing method
remote_signer_url	string | null	Remote signer base URL
remote_signer_verified	boolean	Whether signer verification has completed
created_at	datetime | null	Creation timestamp
updated_at	datetime | null	Last update timestamp

Strategy

Represents an automated Up or Down trading strategy evaluated continuously by Polyscout.

Field	Type	Description
id	uuid	Strategy id
user_id	uuid	Owning user id
wallet_id	uuid	Wallet used for execution
label	string | null	Optional label
asset	BTC | ETH | SOL | XRP	Market asset
timeframe	15m | 1h | 4h | 24h	Market timeframe
trade_amount	number	USDC.e amount per entry
odds_threshold	number | null	Entry odds threshold
minutes_before_end	number	Entry window before event end
stop_loss_percent	number | null	Percent stop-loss from entry
stop_loss_odds	number | null	Absolute odds stop
take_profit_percent	number | null	Percent take-profit
take_profit_odds	number | null	Take-profit odds delta
max_executions_per_event	integer | null	Per-event execution cap
max_entry_slippage	number | null	Maximum entry slippage
ma_filter_enabled	boolean | null	Moving average filter flag
min_volatility	number | null	Minimum volatility threshold
status	active | stopped	Strategy status
started_at	datetime | null	When strategy was activated
created_at	datetime | null	Creation timestamp
updated_at	datetime | null	Last update timestamp

PlaceBet

Represents a one-off conditional bet tied to a specific Polymarket event.

Field	Type	Description
id	uuid	Place-bet id
user_id	uuid	Owning user id
wallet_id	uuid	Wallet used for execution
label	string | null	Optional label
event_slug	string	Polymarket event slug
direction	up | down	Trade direction
trade_amount	number	USDC.e amount
entry_odds	number	Entry odds threshold
max_entry_slippage	number | null	Maximum slippage
stop_loss_percent	number | null	Percent stop-loss
stop_loss_odds	number | null	Absolute odds stop
take_profit_percent	number | null	Percent take-profit
take_profit_odds	number | null	Take-profit odds delta
claim_only	boolean	Claim only after resolution
status	open | triggered | filled | cancelled | expired | failed	Current state
execution_id	uuid | null	Linked execution id
last_error	string | null	Last error message
expires_at	datetime | null	Optional expiry
created_at	datetime | null	Creation timestamp
updated_at	datetime | null	Last update timestamp

Execution

Represents a read-only record created when Polyscout places, manages, or settles a trade.

Field	Type	Description
id	uuid	Execution id
user_id	uuid	Owning user id
wallet_id	uuid	Wallet used
strategy_id	uuid | null	Strategy source
place_bet_id	uuid | null	Place-bet source
event_slug	string	Polymarket event
market_token_id	string | null	Polymarket token id
direction	up | down	Trade direction
trade_amount	number	USDC.e amount
odds_threshold	number | null	Trigger threshold
execution_price	number | null	Executed odds
status	pending | bet_placed | claiming | claimed | failed	Execution state
stop_loss_percent	number | null	Stop-loss percent
stop_loss_odds	number | null	Absolute stop-loss
take_profit_percent	number | null	Take-profit percent
take_profit_delta_odds	number | null	Take-profit odds delta
closed_at	datetime | null	When closed
relayer_tx_hash	string | null	Relayer tx hash
error_message	string | null	Failure reason
created_at	datetime | null	Creation timestamp
updated_at	datetime | null	Last update timestamp