> 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/setup.md).
# Setup
One-time wallet setup (deposit, referral, builder fee)
## Fund the account
> Returns an unsigned two-transaction HyperEVM plan that moves USDC into the wallet's\
> Hyperliquid account. Sign and broadcast both transactions yourself via \`eth\_sendRawTransaction\`\
> on the plan's \`rpcUrl\`. Do \*\*not\*\* use \`signL1Action\`.\
> \
> The \`approve\` is for the exact amount — send both transactions on every deposit.\
> Broadcast approve first, deposit second, with consecutive nonces.
```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"tags":[{"name":"Setup","description":"One-time wallet setup (deposit, referral, builder fee)"}],"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":{"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"}}},"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\")"}}},"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/deposit":{"post":{"operationId":"createDeposit","tags":["Setup"],"summary":"Fund the account","description":"Returns an unsigned two-transaction HyperEVM plan that moves USDC into the wallet's\nHyperliquid account. Sign and broadcast both transactions yourself via `eth_sendRawTransaction`\non the plan's `rpcUrl`. Do **not** use `signL1Action`.\n\nThe `approve` is for the exact amount — send both transactions on every deposit.\nBroadcast approve first, deposit second, with consecutive nonces.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositRequest"}}}},"responses":{"200":{"description":"Deposit plan returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_DepositPlan"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```
## Referral opt-in (one-time)
> Returns an unsigned \`setReferrer\` action, or \`null\` when no referral code is configured\
> or the wallet already has a referrer. Sign with \`signL1Action\` and POST directly to\
> Hyperliquid \`/exchange\`.\
> \
> Hyperliquid only lets a wallet set a referrer while cumulative volume is under $10k.
```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"tags":[{"name":"Setup","description":"One-time wallet setup (deposit, referral, builder fee)"}],"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":{"UserAddressRequest":{"type":"object","required":["userAddress"],"properties":{"userAddress":{"type":"string","description":"EVM wallet address"}}},"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"},"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/referral":{"post":{"operationId":"createReferral","tags":["Setup"],"summary":"Referral opt-in (one-time)","description":"Returns an unsigned `setReferrer` action, or `null` when no referral code is configured\nor the wallet already has a referrer. Sign with `signL1Action` and POST directly to\nHyperliquid `/exchange`.\n\nHyperliquid only lets a wallet set a referrer while cumulative volume is under $10k.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAddressRequest"}}}},"responses":{"200":{"description":"Referral action or null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_ReferralResponse"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```
## Approve builder fee (one-time)
> Returns an unsigned \`approveBuilderFee\` action. Sign with \`signUserSignedAction\` (EIP-712),\
> then POST the signed envelope directly to Hyperliquid \`/exchange\`.\
> \
> Sign once per wallet; afterwards the \`builderFeeNotApproved\` gate stops firing.
```json
{"openapi":"3.0.3","info":{"title":"Boundary Perps API","version":"1.0.0"},"tags":[{"name":"Setup","description":"One-time wallet setup (deposit, referral, builder fee)"}],"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_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"},"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/builder-fee-approval":{"post":{"operationId":"createBuilderFeeApproval","tags":["Setup"],"summary":"Approve builder fee (one-time)","description":"Returns an unsigned `approveBuilderFee` action. Sign with `signUserSignedAction` (EIP-712),\nthen POST the signed envelope directly to Hyperliquid `/exchange`.\n\nSign once per wallet; afterwards the `builderFeeNotApproved` gate stops firing.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Builder fee approval action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_BuilderFeeApproval"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```