# Trading
Position management endpoints. Require Privy JWT authentication.
## Open a position
> Opens a perpetual or delta-neutral position on Hyperliquid via the user's agent wallet.\
> \
> \*\*Order types:\*\*\
> \- \`market\` (default): IOC limit at mark price with 5% slippage buffer\
> \- \`limit\`: GTC limit at the specified \`limitPrice\`\
> \- \`pro\`: Delta-neutral two-leg execution (short perp + long spot for positive funding).\
> Pro mode with \`side=long\` returns 422 until the HyperEVM lending vault launches.\
> \
> \*\*TP/SL:\*\* Include \`tpPrice\` and/or \`slPrice\` to bundle OCO take-profit and stop-loss\
> orders with the entry order (normalTpsl grouping).\
> \
> Requires an active agent wallet approval (via \`/api/auth/approve-agent\`).
```json
{"openapi":"3.1.0","info":{"title":"Zirodelta API","version":"1.0.0"},"tags":[{"name":"Trading","description":"Position management endpoints. Require Privy JWT authentication."}],"servers":[{"url":"https://api.dex.zirodelta.xyz","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Privy-issued JWT. Obtain by connecting your wallet at https://app.zirodelta.com."}},"schemas":{"OpenPositionRequest":{"type":"object","required":["coin","side","size"],"properties":{"coin":{"type":"string","description":"Asset symbol (uppercase)."},"side":{"type":"string","enum":["long","short"],"description":"Position direction. In delta-neutral (pro) mode with side=long, the negative-funding path is blocked until the HyperEVM lending vault launches."},"size":{"type":"number","format":"double","description":"Position size in USDC notional."},"leverage":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Leverage multiplier. Defaults to 1."},"orderType":{"type":"string","enum":["market","limit","pro"],"default":"market","description":"Order type. pro triggers delta-neutral two-leg execution (perp + spot)."},"limitPrice":{"type":"number","format":"double","description":"Required when orderType is limit. Ignored for market orders."},"reduceOnly":{"type":"boolean","default":false,"description":"If true, the order only reduces an existing position."},"tpPrice":{"type":"number","format":"double","description":"Take profit trigger price. Set to 0 or omit to disable."},"slPrice":{"type":"number","format":"double","description":"Stop loss trigger price. Set to 0 or omit to disable."},"spotLimitPrice":{"type":"number","format":"double","description":"Spot leg limit price for delta-neutral (pro) orders. Set to 0 or omit for market execution."}}},"OpenPositionResponse":{"type":"object","required":["message","coin","side","size"],"properties":{"message":{"type":"string"},"coin":{"type":"string"},"side":{"type":"string","enum":["long","short"]},"size":{"type":"number","format":"double","description":"Size in coin units that was submitted."}}},"DNOpenPositionResponse":{"type":"object","required":["message","coin","perpSide","spotSide","size"],"properties":{"message":{"type":"string"},"coin":{"type":"string"},"perpSide":{"type":"string","enum":["long","short"]},"spotSide":{"type":"string","enum":["buy","sell"]},"size":{"type":"number","format":"double","description":"Size in coin units for each leg."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error description."},"retry_after":{"type":"integer","description":"Seconds to wait before retrying. Present only on 429 responses."}}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current rate limit window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the current rate limit window resets.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Invalid request parameters or body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid JWT.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal server error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/positions":{"post":{"operationId":"openPosition","summary":"Open a position","description":"Opens a perpetual or delta-neutral position on Hyperliquid via the user's agent wallet.\n\n**Order types:**\n- `market` (default): IOC limit at mark price with 5% slippage buffer\n- `limit`: GTC limit at the specified `limitPrice`\n- `pro`: Delta-neutral two-leg execution (short perp + long spot for positive funding).\n Pro mode with `side=long` returns 422 until the HyperEVM lending vault launches.\n\n**TP/SL:** Include `tpPrice` and/or `slPrice` to bundle OCO take-profit and stop-loss\norders with the entry order (normalTpsl grouping).\n\nRequires an active agent wallet approval (via `/api/auth/approve-agent`).\n","tags":["Trading"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenPositionRequest"}}}},"responses":{"200":{"description":"Order submitted successfully.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OpenPositionResponse"},{"$ref":"#/components/schemas/DNOpenPositionResponse"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Unprocessable entity. Returned for delta-neutral long (negative funding) orders until the lending vault launches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Database unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Close a position
> Closes an open position for the given coin. The \`id\` path parameter is the coin\
> symbol (e.g. BTC), not a numeric order ID. Hyperliquid positions are keyed by coin.\
> \
> Submits a reduce-only IOC market order for the full current position size.
```json
{"openapi":"3.1.0","info":{"title":"Zirodelta API","version":"1.0.0"},"tags":[{"name":"Trading","description":"Position management endpoints. Require Privy JWT authentication."}],"servers":[{"url":"https://api.dex.zirodelta.xyz","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Privy-issued JWT. Obtain by connecting your wallet at https://app.zirodelta.com."}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current rate limit window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the current rate limit window resets.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Invalid request parameters or body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid JWT.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal server error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error description."},"retry_after":{"type":"integer","description":"Seconds to wait before retrying. Present only on 429 responses."}}}}},"paths":{"/api/positions/{id}":{"delete":{"operationId":"closePosition","summary":"Close a position","description":"Closes an open position for the given coin. The `id` path parameter is the coin\nsymbol (e.g. BTC), not a numeric order ID. Hyperliquid positions are keyed by coin.\n\nSubmits a reduce-only IOC market order for the full current position size.\n","tags":["Trading"],"parameters":[{"name":"id","in":"path","required":true,"description":"Coin symbol of the position to close (uppercase). Example: BTC, ETH.","schema":{"type":"string"}}],"responses":{"200":{"description":"Close order submitted.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["message","coin"],"properties":{"message":{"type":"string"},"coin":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No open position found for this coin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/InternalError"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.zirodelta.com/api-reference/trading.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.