> 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/models.md).

# Models

## The DepositRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"DepositRequest":{"type":"object","required":["userAddress","amount"],"properties":{"userAddress":{"type":"string","description":"EVM wallet address that signs and owns the Hyperliquid position"},"amount":{"type":"string","description":"USDC amount to deposit"}}}}}}
```

## The UserAddressRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"UserAddressRequest":{"type":"object","required":["userAddress"],"properties":{"userAddress":{"type":"string","description":"EVM wallet address"}}}}}}
```

## The QuoteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"QuoteRequest":{"type":"object","required":["side","upperBound","lowerBound","wager"],"properties":{"side":{"type":"string","enum":["upper_first","lower_first"],"description":"Which bound you bet on being touched first"},"upperBound":{"type":"string","description":"Upper price boundary"},"lowerBound":{"type":"string","description":"Lower price boundary"},"wager":{"type":"string","description":"Isolated margin amount in USDC"},"coin":{"type":"string","description":"Asset name (e.g. BTC, ETH). Optional — defaults to the launch asset if omitted."}}}}}}
```

## The ProposalRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ProposalRequest":{"type":"object","required":["side","upperBound","lowerBound","wager","userAddress"],"properties":{"side":{"type":"string","enum":["upper_first","lower_first"]},"upperBound":{"type":"string"},"lowerBound":{"type":"string"},"wager":{"type":"string"},"coin":{"type":"string","description":"Optional — defaults to the launch asset if omitted"},"userAddress":{"type":"string","description":"EVM wallet that signs and owns the position"}}}}}}
```

## The ExecuteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ExecuteRequest":{"type":"object","required":["actions"],"properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/SignedAction"},"description":"Signed actions in order (from proposals or cash-out)"}}},"SignedAction":{"type":"object","required":["kind","action","nonce","signature"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close","take_profit","approve_builder_fee","set_referrer","withdraw"],"description":"Action kind — must match the unsigned action's kind. Entry bundles use update_leverage + entry; cash-out bundles use cancel + cash_out_close."},"action":{"$ref":"#/components/schemas/HlAction"},"nonce":{"type":"number","description":"Monotonic nonce in milliseconds"},"signature":{"description":"Hex-encoded signature string, or an {r, s, v} object"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The SignedAction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"SignedAction":{"type":"object","required":["kind","action","nonce","signature"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close","take_profit","approve_builder_fee","set_referrer","withdraw"],"description":"Action kind — must match the unsigned action's kind. Entry bundles use update_leverage + entry; cash-out bundles use cancel + cash_out_close."},"action":{"$ref":"#/components/schemas/HlAction"},"nonce":{"type":"number","description":"Monotonic nonce in milliseconds"},"signature":{"description":"Hex-encoded signature string, or an {r, s, v} object"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The WithdrawRequest object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"WithdrawRequest":{"type":"object","required":["userAddress","amount"],"properties":{"userAddress":{"type":"string","description":"EVM wallet address"},"amount":{"type":"string","description":"USDC amount to withdraw"}}}}}}
```

## The ErrorEnvelope object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"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)"}}}}}}
```

## The PaginationMeta object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"totalItems":{"type":"integer"},"currentPage":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}
```

## The ApiResponse\_DepositPlan object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_DepositPlan":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/DepositPlan"}}},"DepositPlan":{"type":"object","required":["usdcToken","depositContract","rpcUrl","from","amount","txs"],"properties":{"usdcToken":{"type":"string","description":"USDC ERC-20 contract address"},"depositContract":{"type":"string","description":"Pull-based deposit contract address"},"rpcUrl":{"type":"string","description":"HyperEVM RPC URL — broadcast both signed txs here"},"from":{"type":"string","description":"The signing wallet address"},"amount":{"type":"string","description":"USDC amount"},"txs":{"type":"array","items":{"$ref":"#/components/schemas/EvmTx"},"minItems":2,"maxItems":2,"description":"[approve, deposit] — sign and broadcast IN ORDER"}}},"EvmTx":{"type":"object","required":["chainId","to","data","value"],"properties":{"chainId":{"type":"integer","description":"999 for mainnet, 998 for testnet"},"to":{"type":"string","description":"Contract address"},"data":{"type":"string","description":"Encoded calldata"},"value":{"type":"string","description":"ETH value (typically \"0\")"}}}}}}
```

## The ApiResponse\_ReferralResponse object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_ReferralResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ReferralResponse"}}},"ReferralResponse":{"nullable":true,"type":"object","properties":{"kind":{"type":"string","enum":["set_referrer"]},"action":{"$ref":"#/components/schemas/HlAction"}},"description":"null when no referral code is configured or wallet already has a referrer"},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The ApiResponse\_BuilderFeeApproval object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_BuilderFeeApproval":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BuilderFeeApproval"}}},"BuilderFeeApproval":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["approve_builder_fee"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The ApiResponse\_Limits object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_Limits":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Limits"}}},"Limits":{"type":"object","required":["coin","mark","maxLeverage","maxBoundDistance","minAgainstDistance"],"properties":{"coin":{"type":"string"},"mark":{"type":"string","description":"Snapshot mark price at fetch time"},"maxLeverage":{"type":"integer"},"maxBoundDistance":{"type":"string","description":"Each bound must be within this fraction of mark (e.g. \"0.1\" = 10%)"},"minAgainstDistance":{"type":"object","required":["upper_first","lower_first"],"properties":{"upper_first":{"type":"string","description":"LONG: lower bound must be >= this fraction below mark"},"lower_first":{"type":"string","description":"SHORT: upper bound must be >= this fraction above mark"}}}}}}}}
```

## The ApiResponse\_Construction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_Construction":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Construction"}}},"Construction":{"type":"object","required":["direction","leverage","notional","coinSize","chosenBound","losingBound","takeProfitPrice","liquidationPrice","payoutMultiple","payoutEstimate","maxSlippage","entryPrice","wager"],"properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer","description":"Integer, rounded down"},"notional":{"type":"string","description":"leverage * wager"},"coinSize":{"type":"string"},"chosenBound":{"type":"string","description":"The bound you bet on — becomes take-profit"},"losingBound":{"type":"string","description":"The opposing bound — liquidation level"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string","description":"Pre-trade estimate at the mark"},"payoutMultiple":{"type":"string","description":"profit / wager (NOT total return — add 1 for total-return multiple)"},"payoutEstimate":{"type":"string","description":"Profit in USDC if won, before fees and funding"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string","description":"Mark price used to price"},"wager":{"type":"string"}}}}}}
```

## The ApiResponse\_ProposalResult object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_ProposalResult":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ProposalResult"}}},"ProposalResult":{"type":"object","required":["betId","state","proposalExpiresAt","construction","unsignedActions"],"properties":{"betId":{"type":"string"},"state":{"type":"string","enum":["proposed"]},"proposalExpiresAt":{"type":"string","format":"date-time","description":"Sign and execute BEFORE this time"},"construction":{"$ref":"#/components/schemas/Construction"},"unsignedActions":{"type":"array","items":{"$ref":"#/components/schemas/UnsignedAction"}}}},"Construction":{"type":"object","required":["direction","leverage","notional","coinSize","chosenBound","losingBound","takeProfitPrice","liquidationPrice","payoutMultiple","payoutEstimate","maxSlippage","entryPrice","wager"],"properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer","description":"Integer, rounded down"},"notional":{"type":"string","description":"leverage * wager"},"coinSize":{"type":"string"},"chosenBound":{"type":"string","description":"The bound you bet on — becomes take-profit"},"losingBound":{"type":"string","description":"The opposing bound — liquidation level"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string","description":"Pre-trade estimate at the mark"},"payoutMultiple":{"type":"string","description":"profit / wager (NOT total return — add 1 for total-return multiple)"},"payoutEstimate":{"type":"string","description":"Profit in USDC if won, before fees and funding"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string","description":"Mark price used to price"},"wager":{"type":"string"}}},"UnsignedAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The ApiResponse\_Bet object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ApiResponse\_BetList object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ApiResponse\_CashOutResult object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_CashOutResult":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/CashOutResult"}}},"CashOutResult":{"type":"object","required":["betId","unsignedActions"],"properties":{"betId":{"type":"string"},"unsignedActions":{"type":"array","items":{"$ref":"#/components/schemas/UnsignedAction"},"minItems":2,"maxItems":2,"description":"[cancel, cash_out_close]"}}},"UnsignedAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The ApiResponse\_WithdrawAction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ApiResponse_WithdrawAction":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WithdrawAction"}}},"WithdrawAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["withdraw"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The HlAction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The EvmTx object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"EvmTx":{"type":"object","required":["chainId","to","data","value"],"properties":{"chainId":{"type":"integer","description":"999 for mainnet, 998 for testnet"},"to":{"type":"string","description":"Contract address"},"data":{"type":"string","description":"Encoded calldata"},"value":{"type":"string","description":"ETH value (typically \"0\")"}}}}}}
```

## The DepositPlan object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"DepositPlan":{"type":"object","required":["usdcToken","depositContract","rpcUrl","from","amount","txs"],"properties":{"usdcToken":{"type":"string","description":"USDC ERC-20 contract address"},"depositContract":{"type":"string","description":"Pull-based deposit contract address"},"rpcUrl":{"type":"string","description":"HyperEVM RPC URL — broadcast both signed txs here"},"from":{"type":"string","description":"The signing wallet address"},"amount":{"type":"string","description":"USDC amount"},"txs":{"type":"array","items":{"$ref":"#/components/schemas/EvmTx"},"minItems":2,"maxItems":2,"description":"[approve, deposit] — sign and broadcast IN ORDER"}}},"EvmTx":{"type":"object","required":["chainId","to","data","value"],"properties":{"chainId":{"type":"integer","description":"999 for mainnet, 998 for testnet"},"to":{"type":"string","description":"Contract address"},"data":{"type":"string","description":"Encoded calldata"},"value":{"type":"string","description":"ETH value (typically \"0\")"}}}}}}
```

## The ReferralResponse object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ReferralResponse":{"nullable":true,"type":"object","properties":{"kind":{"type":"string","enum":["set_referrer"]},"action":{"$ref":"#/components/schemas/HlAction"}},"description":"null when no referral code is configured or wallet already has a referrer"},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The BuilderFeeApproval object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"BuilderFeeApproval":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["approve_builder_fee"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The Limits object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"Limits":{"type":"object","required":["coin","mark","maxLeverage","maxBoundDistance","minAgainstDistance"],"properties":{"coin":{"type":"string"},"mark":{"type":"string","description":"Snapshot mark price at fetch time"},"maxLeverage":{"type":"integer"},"maxBoundDistance":{"type":"string","description":"Each bound must be within this fraction of mark (e.g. \"0.1\" = 10%)"},"minAgainstDistance":{"type":"object","required":["upper_first","lower_first"],"properties":{"upper_first":{"type":"string","description":"LONG: lower bound must be >= this fraction below mark"},"lower_first":{"type":"string","description":"SHORT: upper bound must be >= this fraction above mark"}}}}}}}}
```

## The Construction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"Construction":{"type":"object","required":["direction","leverage","notional","coinSize","chosenBound","losingBound","takeProfitPrice","liquidationPrice","payoutMultiple","payoutEstimate","maxSlippage","entryPrice","wager"],"properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer","description":"Integer, rounded down"},"notional":{"type":"string","description":"leverage * wager"},"coinSize":{"type":"string"},"chosenBound":{"type":"string","description":"The bound you bet on — becomes take-profit"},"losingBound":{"type":"string","description":"The opposing bound — liquidation level"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string","description":"Pre-trade estimate at the mark"},"payoutMultiple":{"type":"string","description":"profit / wager (NOT total return — add 1 for total-return multiple)"},"payoutEstimate":{"type":"string","description":"Profit in USDC if won, before fees and funding"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string","description":"Mark price used to price"},"wager":{"type":"string"}}}}}}
```

## The UnsignedAction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"UnsignedAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The ProposalResult object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"ProposalResult":{"type":"object","required":["betId","state","proposalExpiresAt","construction","unsignedActions"],"properties":{"betId":{"type":"string"},"state":{"type":"string","enum":["proposed"]},"proposalExpiresAt":{"type":"string","format":"date-time","description":"Sign and execute BEFORE this time"},"construction":{"$ref":"#/components/schemas/Construction"},"unsignedActions":{"type":"array","items":{"$ref":"#/components/schemas/UnsignedAction"}}}},"Construction":{"type":"object","required":["direction","leverage","notional","coinSize","chosenBound","losingBound","takeProfitPrice","liquidationPrice","payoutMultiple","payoutEstimate","maxSlippage","entryPrice","wager"],"properties":{"direction":{"type":"string","enum":["long","short"]},"leverage":{"type":"integer","description":"Integer, rounded down"},"notional":{"type":"string","description":"leverage * wager"},"coinSize":{"type":"string"},"chosenBound":{"type":"string","description":"The bound you bet on — becomes take-profit"},"losingBound":{"type":"string","description":"The opposing bound — liquidation level"},"takeProfitPrice":{"type":"string"},"liquidationPrice":{"type":"string","description":"Pre-trade estimate at the mark"},"payoutMultiple":{"type":"string","description":"profit / wager (NOT total return — add 1 for total-return multiple)"},"payoutEstimate":{"type":"string","description":"Profit in USDC if won, before fees and funding"},"maxSlippage":{"type":"string"},"entryPrice":{"type":"string","description":"Mark price used to price"},"wager":{"type":"string"}}},"UnsignedAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The CashOutResult object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"CashOutResult":{"type":"object","required":["betId","unsignedActions"],"properties":{"betId":{"type":"string"},"unsignedActions":{"type":"array","items":{"$ref":"#/components/schemas/UnsignedAction"},"minItems":2,"maxItems":2,"description":"[cancel, cash_out_close]"}}},"UnsignedAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["update_leverage","entry","cancel","cash_out_close"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The WithdrawAction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"WithdrawAction":{"type":"object","required":["kind","action"],"properties":{"kind":{"type":"string","enum":["withdraw"]},"action":{"$ref":"#/components/schemas/HlAction"}}},"HlAction":{"type":"object","additionalProperties":true,"description":"Opaque Hyperliquid action object. Bound builds it; you sign it byte for byte\nand never edit it. Bound re-derives the expected body when you relay it back.\n"}}}}
```

## The VenueRefs object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"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}}}}}}
```

## The BetActuals object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The BetConstruction object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The Bet object

```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```