> For the complete documentation index, see [llms.txt](https://bound-1.gitbook.io/bound-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bound-1.gitbook.io/bound-docs/developer-guide/api-reference/read.md).
# Read
List and read bets
## List your bets
> Paginated. Regular users always see only their own bets — the account scope is enforced\
> server-side.\
> \
> Filters use the \`field\_eq=value\` grammar. A bare \`?state=…\` does \*\*not\*\* filter.\
> \`evmAddress\_eq\` must be lower-cased.
```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"tags":[{"name":"Read","description":"List and read bets"}],"servers":[{"url":"https://api.bound.exchange","description":"Production"},{"url":"https://testnet-api.bound.exchange","description":"Testnet"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token from `POST /auth/authenticate`"}},"schemas":{"ApiResponse_BetList":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Bet"}},"metaData":{"$ref":"#/components/schemas/PaginationMeta"}}},"Bet":{"type":"object","required":["_id","coin","evmAddress","side","upperBound","lowerBound","wager","construction","state","proposalExpiresAt","venueRefs","actuals","createdAt","updatedAt"],"properties":{"_id":{"type":"string","description":"Bet ID (the list returns `_id`; only /proposals returns `betId`)"},"accountId":{"type":"string","description":"Internal account identifier"},"coin":{"type":"string"},"evmAddress":{"type":"string","description":"Stored lower-cased"},"side":{"type":"string","enum":["upper_first","lower_first"]},"upperBound":{"type":"string"},"lowerBound":{"type":"string"},"wager":{"type":"string","description":"Isolated margin, USDC"},"construction":{"$ref":"#/components/schemas/BetConstruction"},"state":{"type":"string","enum":["proposed","active","won","lost","cashed_out","voided","aborted"]},"proposalExpiresAt":{"type":"string","format":"date-time"},"activatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Entry fill verified -> active"},"resolvedAt":{"type":"string","format":"date-time","nullable":true,"description":"Reached won / lost / cashed_out / voided"},"abortReason":{"type":"string","nullable":true,"enum":["proposal_expired","user_abandoned",null]},"voidReason":{"type":"string","nullable":true,"enum":["tp_cancelled","margin_changed","position_closed","position_resized","other",null]},"cashOutPending":{"type":"boolean","description":"True once a cash-out was requested"},"boundBreachFlagged":{"type":"boolean","description":"The real fill put liquidation inside the losing bound"},"venueRefs":{"$ref":"#/components/schemas/VenueRefs"},"actuals":{"$ref":"#/components/schemas/BetActuals"},"relayClaimedAt":{"type":"string","format":"date-time","nullable":true,"description":"Internal relay-claim timestamp"},"createdAt":{"type":"number","description":"Epoch ms (NOT an ISO string)"},"updatedAt":{"type":"number","description":"Epoch ms — bumped by every write"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"description":"Internal — soft-delete timestamp from BaseEntity. May stop being serialized."}}},"BetConstruction":{"type":"object","description":"Construction snapshot recorded at proposal time. Contains the same pricing fields\nas Construction (except `wager`, which is stored at the top-level Bet) plus 4\nvenue-snapshot fields.\n","properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer"},"notional":{"type":"string"},"coinSize":{"type":"string"},"chosenBound":{"type":"string"},"losingBound":{"type":"string"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string"},"payoutMultiple":{"type":"string"},"payoutEstimate":{"type":"string"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string"},"assetIndex":{"type":"integer"},"szDecimals":{"type":"integer"},"maintenanceMarginFraction":{"type":"string"},"builderFeeRate":{"type":"string"}}},"VenueRefs":{"type":"object","properties":{"entryOid":{"type":"string","nullable":true},"takeProfitOid":{"type":"string","nullable":true,"description":"null for up to one monitor cycle (~30s) right after execute"},"closeOid":{"type":"string","nullable":true}}},"BetActuals":{"type":"object","description":"Post-fill data — every field null until the venue event lands","properties":{"actualEntryPrice":{"type":"string","nullable":true},"actualLiquidationPrice":{"type":"string","nullable":true,"description":"On-venue value — use this once active"},"actualPayoutMultiple":{"type":"string","nullable":true},"actualCoinSize":{"type":"string","nullable":true},"actualMarginUsed":{"type":"string","nullable":true},"fundingAtActivation":{"type":"string","nullable":true},"finalProceeds":{"type":"string","nullable":true,"description":"GROSS realized PnL — before fees and funding. Not the user's result."},"feesPaid":{"type":"string","nullable":true,"description":"Close-side exchange fee"},"fundingPaid":{"type":"string","nullable":true,"description":"Signed; negative = paid"},"netProceeds":{"type":"string","nullable":true,"description":"Authoritative NET (finalProceeds - fees + funding). Nullable — best-effort.\nWhen null, recompute from Hyperliquid userFills + userFunding.\n"}}},"PaginationMeta":{"type":"object","properties":{"totalItems":{"type":"integer"},"currentPage":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code (26xxx for Boundary Perps errors)"},"message":{"type":"string","description":"Error message key"},"details":{"type":"string","description":"Human-readable detail (present on some errors)"}}}},"responses":{"ErrorResponse":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/which-first":{"get":{"operationId":"listBets","tags":["Read"],"summary":"List your bets","description":"Paginated. Regular users always see only their own bets — the account scope is enforced\nserver-side.\n\nFilters use the `field_eq=value` grammar. A bare `?state=…` does **not** filter.\n`evmAddress_eq` must be lower-cased.\n","parameters":[{"name":"state_eq","in":"query","required":false,"schema":{"type":"string","enum":["proposed","active","won","lost","cashed_out","voided","aborted"]},"description":"Filter by bet state"},{"name":"evmAddress_eq","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by wallet address (must be lower-cased)"},{"name":"coin_eq","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by asset name"},{"name":"side_eq","in":"query","required":false,"schema":{"type":"string","enum":["upper_first","lower_first"]},"description":"Filter by bet side"},{"name":"createdAt_gte","in":"query","required":false,"schema":{"type":"number"},"description":"Created at lower bound (epoch ms)"},{"name":"createdAt_lte","in":"query","required":false,"schema":{"type":"number"},"description":"Created at upper bound (epoch ms)"},{"name":"activatedAt_gte","in":"query","required":false,"schema":{"type":"number"},"description":"Activated at lower bound (epoch ms)"},{"name":"activatedAt_lte","in":"query","required":false,"schema":{"type":"number"},"description":"Activated at upper bound (epoch ms)"},{"name":"resolvedAt_gte","in":"query","required":false,"schema":{"type":"number"},"description":"Resolved at lower bound (epoch ms)"},{"name":"resolvedAt_lte","in":"query","required":false,"schema":{"type":"number"},"description":"Resolved at upper bound (epoch ms)"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Items per page"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort field (prefix with `-` for descending, e.g. `-createdAt`)"}],"responses":{"200":{"description":"Paginated list of bets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_BetList"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```
## Read one bet
> Owner only. A well-formed but unknown or foreign id returns \`26001\` or \`26002\`.\
> An \`id\` that is not 24-hex does not match the route at all and returns a plain 404.
```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"tags":[{"name":"Read","description":"List and read bets"}],"servers":[{"url":"https://api.bound.exchange","description":"Production"},{"url":"https://testnet-api.bound.exchange","description":"Testnet"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token from `POST /auth/authenticate`"}},"parameters":{"BetId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Bet ID (24-char hex string)"}},"schemas":{"ApiResponse_Bet":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Bet"}}},"Bet":{"type":"object","required":["_id","coin","evmAddress","side","upperBound","lowerBound","wager","construction","state","proposalExpiresAt","venueRefs","actuals","createdAt","updatedAt"],"properties":{"_id":{"type":"string","description":"Bet ID (the list returns `_id`; only /proposals returns `betId`)"},"accountId":{"type":"string","description":"Internal account identifier"},"coin":{"type":"string"},"evmAddress":{"type":"string","description":"Stored lower-cased"},"side":{"type":"string","enum":["upper_first","lower_first"]},"upperBound":{"type":"string"},"lowerBound":{"type":"string"},"wager":{"type":"string","description":"Isolated margin, USDC"},"construction":{"$ref":"#/components/schemas/BetConstruction"},"state":{"type":"string","enum":["proposed","active","won","lost","cashed_out","voided","aborted"]},"proposalExpiresAt":{"type":"string","format":"date-time"},"activatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Entry fill verified -> active"},"resolvedAt":{"type":"string","format":"date-time","nullable":true,"description":"Reached won / lost / cashed_out / voided"},"abortReason":{"type":"string","nullable":true,"enum":["proposal_expired","user_abandoned",null]},"voidReason":{"type":"string","nullable":true,"enum":["tp_cancelled","margin_changed","position_closed","position_resized","other",null]},"cashOutPending":{"type":"boolean","description":"True once a cash-out was requested"},"boundBreachFlagged":{"type":"boolean","description":"The real fill put liquidation inside the losing bound"},"venueRefs":{"$ref":"#/components/schemas/VenueRefs"},"actuals":{"$ref":"#/components/schemas/BetActuals"},"relayClaimedAt":{"type":"string","format":"date-time","nullable":true,"description":"Internal relay-claim timestamp"},"createdAt":{"type":"number","description":"Epoch ms (NOT an ISO string)"},"updatedAt":{"type":"number","description":"Epoch ms — bumped by every write"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"description":"Internal — soft-delete timestamp from BaseEntity. May stop being serialized."}}},"BetConstruction":{"type":"object","description":"Construction snapshot recorded at proposal time. Contains the same pricing fields\nas Construction (except `wager`, which is stored at the top-level Bet) plus 4\nvenue-snapshot fields.\n","properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer"},"notional":{"type":"string"},"coinSize":{"type":"string"},"chosenBound":{"type":"string"},"losingBound":{"type":"string"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string"},"payoutMultiple":{"type":"string"},"payoutEstimate":{"type":"string"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string"},"assetIndex":{"type":"integer"},"szDecimals":{"type":"integer"},"maintenanceMarginFraction":{"type":"string"},"builderFeeRate":{"type":"string"}}},"VenueRefs":{"type":"object","properties":{"entryOid":{"type":"string","nullable":true},"takeProfitOid":{"type":"string","nullable":true,"description":"null for up to one monitor cycle (~30s) right after execute"},"closeOid":{"type":"string","nullable":true}}},"BetActuals":{"type":"object","description":"Post-fill data — every field null until the venue event lands","properties":{"actualEntryPrice":{"type":"string","nullable":true},"actualLiquidationPrice":{"type":"string","nullable":true,"description":"On-venue value — use this once active"},"actualPayoutMultiple":{"type":"string","nullable":true},"actualCoinSize":{"type":"string","nullable":true},"actualMarginUsed":{"type":"string","nullable":true},"fundingAtActivation":{"type":"string","nullable":true},"finalProceeds":{"type":"string","nullable":true,"description":"GROSS realized PnL — before fees and funding. Not the user's result."},"feesPaid":{"type":"string","nullable":true,"description":"Close-side exchange fee"},"fundingPaid":{"type":"string","nullable":true,"description":"Signed; negative = paid"},"netProceeds":{"type":"string","nullable":true,"description":"Authoritative NET (finalProceeds - fees + funding). Nullable — best-effort.\nWhen null, recompute from Hyperliquid userFills + userFunding.\n"}}},"ErrorEnvelope":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code (26xxx for Boundary Perps errors)"},"message":{"type":"string","description":"Error message key"},"details":{"type":"string","description":"Human-readable detail (present on some errors)"}}}},"responses":{"ErrorResponse":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/which-first/{id}":{"get":{"operationId":"getBet","tags":["Read"],"summary":"Read one bet","description":"Owner only. A well-formed but unknown or foreign id returns `26001` or `26002`.\nAn `id` that is not 24-hex does not match the route at all and returns a plain 404.\n","parameters":[{"$ref":"#/components/parameters/BetId"}],"responses":{"200":{"description":"Single bet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Bet"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"404":{"description":"Bet not found"}}}}}}
```