> For the complete documentation index, see [llms.txt](https://docs.afx.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.afx.xyz/api-reference/websocket/user-data.md).

# User Data

## Account / Order / Position State

> Subscribe to real-time account, order, and position state updates.\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "aopState", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/aopState":{"post":{"operationId":"wsAopState","summary":"Account / Order / Position State","tags":["User Data"],"description":"Subscribe to real-time account, order, and position state updates.\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"aopState\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AopStatePush"}}}}}}}},"components":{"schemas":{"AopStatePush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"`snapshot` or `incremental`"},"sequence":{"type":"integer","description":"Sequence number"},"timestamp":{"type":"integer","description":"Timestamp (ms)"},"userAddr":{"type":"string","description":"User wallet address"},"aop":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"currency":{"type":"integer","description":"Currency code (1=USDC)"},"balance":{"type":"string","description":"Total balance"},"availableBalance":{"type":"string","description":"Available for trading"},"availableTransferBalance":{"type":"string","description":"Available for withdrawal/transfer"},"equity":{"type":"string","description":"Account equity (balance + unrealized P&L)"},"status":{"type":"string","description":"NORMAL or LIQUIDATING"},"takerFeeRatio":{"type":"string","description":"Taker fee rate"},"makerFeeRatio":{"type":"string","description":"Maker fee rate"}}}},"orders":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbol":{"type":"string","description":"Symbol name"},"ordId":{"type":"integer","description":"System order ID"},"clOrdId":{"type":"integer","description":"Client order ID"},"parentOrdId":{"type":"integer","description":"Parent order ID (TP/SL)"},"ordPx":{"type":"string","description":"Order price"},"ordQty":{"type":"string","description":"Order quantity"},"triggerPx":{"type":"string","description":"Trigger price (conditional orders)"},"ordStatus":{"type":"string","description":"NEW, PARTIALLY_FILLED, FILLED, CANCELED"},"ordType":{"type":"string","description":"LIMIT, MARKET"},"ordSide":{"type":"string","description":"BUY, SELL"},"timeInForce":{"type":"string","description":"GTC, IOC, FOK, POST_ONLY"},"reduceOnly":{"type":"string","description":"NONE, REDUCE_ONLY, TP_FROM_POSITION, SL_FROM_POSITION"},"filledQty":{"type":"string","description":"Cumulative filled quantity"},"leavesQty":{"type":"string","description":"Remaining quantity"},"cumFilledValue":{"type":"string","description":"Cumulative filled value"}}}},"positions":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbolCode":{"type":"integer","description":"Symbol code"},"symbol":{"type":"string","description":"Symbol name"},"leverage":{"type":"string","description":"Current leverage"},"longSize":{"type":"string","description":"Long position size"},"longEntryValue":{"type":"string","description":"Long position entry notional"},"shortSize":{"type":"string","description":"Short position size"},"shortEntryValue":{"type":"string","description":"Short position entry notional"},"posMode":{"type":"string","description":"ONE_WAY or HEDGE"},"posMarginMode":{"type":"string","description":"CROSS or ISOLATED"},"assignedPosBalance":{"type":"string","description":"Assigned margin (isolated mode)"},"unrealizedPnl":{"type":"string","description":"Unrealized P&L"},"cumRealizedPnl":{"type":"string","description":"Cumulative realized P&L"},"curMarkPx":{"type":"string","description":"Current mark price"},"cumTransactionFee":{"type":"string","description":"Cumulative trading fees"},"marginTableId":{"type":"integer","description":"Risk limit table ID"}}}},"settings":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"leverage":{"type":"array","description":"[posMode, leverage]"}}}}}}}}}}}}}
````

## Order History

> Subscribe to order execution history updates.\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "orderHist", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/orderHist":{"post":{"operationId":"wsOrderHist","summary":"Order History","tags":["User Data"],"description":"Subscribe to order execution history updates.\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"orderHist\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHistPush"}}}}}}}},"components":{"schemas":{"OrderHistPush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"`snapshot` or `incremental`"},"orderHists":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbol":{"type":"string","description":"Symbol name"},"ordId":{"type":"integer","description":"System order ID"},"execId":{"type":"integer","description":"Execution ID"},"clOrdId":{"type":"integer","description":"Client order ID"},"transactionTime":{"type":"integer","description":"Timestamp (ms)"},"ordType":{"type":"string","description":"LIMIT or MARKET"},"ordSide":{"type":"string","description":"BUY or SELL"},"execStatus":{"type":"string","description":"NEW, FILLED, CANCELED, PARTIALLY_FILLED"},"ordPx":{"type":"string","description":"Order price"},"execPx":{"type":"string","description":"Execution price"},"triggerPx":{"type":"string","description":"Trigger price (conditional orders)"},"execQty":{"type":"string","description":"Execution quantity"},"ordQty":{"type":"string","description":"Original order quantity"},"reduceOnly":{"type":"string","description":"NONE, REDUCE_ONLY, TP_FROM_POSITION, SL_FROM_POSITION"},"slippagePct":{"type":"string","description":"Slippage percentage"}}}}}}}}}}}
````

## User Fills

> Subscribe to user trade fill events.\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "userFilled", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/userFilled":{"post":{"operationId":"wsUserFilled","summary":"User Fills","tags":["User Data"],"description":"Subscribe to user trade fill events.\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"userFilled\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFilledPush"}}}}}}}},"components":{"schemas":{"UserFilledPush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"`snapshot` or `incremental`"},"userFills":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbol":{"type":"string","description":"Symbol name"},"ordId":{"type":"integer","description":"System order ID"},"execId":{"type":"integer","description":"Execution ID"},"ordSide":{"type":"string","description":"BUY or SELL"},"execStatus":{"type":"string","description":"FILLED, PARTIALLY_FILLED"},"ordPx":{"type":"string","description":"Order price"},"filledPx":{"type":"string","description":"Actual fill price"},"execQty":{"type":"string","description":"Fill quantity"},"ordQty":{"type":"string","description":"Original order quantity"},"ordType":{"type":"string","description":"LIMIT or MARKET"},"openFee":{"type":"string","description":"Fee for opening position"},"closeFee":{"type":"string","description":"Fee for closing position"},"posLongTerm":{"type":"integer","description":"Long position cycle identifier"},"posShortTerm":{"type":"integer","description":"Short position cycle identifier"},"txHash":{"type":"string","description":"On-chain transaction hash"},"transactionTime":{"type":"integer","description":"Timestamp (ms)"}}}}}}}}}}}
````

## Closed Position

> Subscribe to closed position events (aggregated P\&L per position cycle).\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "closedPosition", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/closedPosition":{"post":{"operationId":"wsClosedPosition","summary":"Closed Position","tags":["User Data"],"description":"Subscribe to closed position events (aggregated P&L per position cycle).\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"closedPosition\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosedPositionPush"}}}}}}}},"components":{"schemas":{"ClosedPositionPush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"`snapshot` or `incremental`"},"closedPositions":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbolCode":{"type":"integer","description":"Symbol code"},"symbol":{"type":"string","description":"Symbol name"},"side":{"type":"string","description":"LONG or SHORT"},"term":{"type":"integer","description":"Position cycle (increments each open from zero)"},"size":{"type":"string","description":"Total traded quantity"},"ordPx":{"type":"string","description":"Weighted avg opening price"},"closePx":{"type":"string","description":"Weighted avg closing price"},"closedPnl":{"type":"string","description":"Net P&L"},"tradingFees":{"type":"string","description":"Total trading fees"},"fundingFees":{"type":"string","description":"Cumulative funding fees"},"realisedPnl":{"type":"string","description":"Realized P&L (after fees)"},"roi":{"type":"string","description":"ROI percentage (e.g. '15.25' = 15.25%)"},"leverage":{"type":"string","description":"Max leverage during position"},"openTime":{"type":"integer","description":"Open time (ms)"},"closedTime":{"type":"integer","description":"Close time (ms)"}}}}}}}}}}}
````

## User Funding

> Subscribe to user funding fee settlement events.\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "userFunding", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/userFunding":{"post":{"operationId":"wsUserFunding","summary":"User Funding","tags":["User Data"],"description":"Subscribe to user funding fee settlement events.\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"userFunding\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFundingPush"}}}}}}}},"components":{"schemas":{"UserFundingPush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"`snapshot` or `incremental`"},"funding":{"type":"array","items":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"symbol":{"type":"string","description":"Symbol name"},"posSize":{"type":"string","description":"Position size at settlement"},"posSide":{"type":"string","description":"LONG or SHORT"},"fundingRate":{"type":"string","description":"Applied funding rate"},"fundingFee":{"type":"string","description":"Funding fee amount (negative = paid, positive = received)"},"transactionTime":{"type":"integer","description":"Settlement timestamp (ms)"}}}}}}}}}}}
````

## User Events

> Subscribe to general user events (order acks, agent approvals, vault deposits/withdrawals).\
> \
> \`\`\`json\
> { "method": "subscribe", "subscription": { "type": "userEvent", "userAddress": "0xabc..." } }\
> \`\`\`\
> \
> \| Param | Type | Required |\
> \|-------|------|----------|\
> \| userAddress | string | Yes |\
> \
> Event types: \`perpOrder\`, \`approveAgent\`, \`actionAck\`, \`vaultDeposit\`, \`vaultWithdraw\`<br>

````json
{"openapi":"3.0.3","info":{"title":"AFX DEX WebSocket API","version":"1.0.0"},"servers":[{"url":"wss://ws.afx.xyz/ws/dex","description":"Mainnet"},{"url":"wss://ws-testnet.afx.xyz/ws/dex","description":"Testnet"}],"paths":{"/ws/subscribe/userEvent":{"post":{"operationId":"wsUserEvent","summary":"User Events","tags":["User Data"],"description":"Subscribe to general user events (order acks, agent approvals, vault deposits/withdrawals).\n\n```json\n{ \"method\": \"subscribe\", \"subscription\": { \"type\": \"userEvent\", \"userAddress\": \"0xabc...\" } }\n```\n\n| Param | Type | Required |\n|-------|------|----------|\n| userAddress | string | Yes |\n\nEvent types: `perpOrder`, `approveAgent`, `actionAck`, `vaultDeposit`, `vaultWithdraw`\n","responses":{"200":{"description":"Push data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserEventPush"}}}}}}}},"components":{"schemas":{"UserEventPush":{"type":"object","properties":{"channel":{"type":"string"},"data":{"type":"object","properties":{"userAddr":{"type":"string","description":"User wallet address"},"sequence":{"type":"integer","description":"Sequence number"},"timestamp":{"type":"integer","description":"Timestamp (ms)"},"events":{"type":"array","items":{"type":"object","properties":{"eventType":{"type":"string","description":"`perpOrder`, `approveAgent`, `actionAck`, `vaultDeposit`, `vaultWithdraw`"},"event":{"type":"array","description":"Event data (structure varies by eventType)"}}}}}}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.afx.xyz/api-reference/websocket/user-data.md?ask=<question>
```

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.