> ## Documentation Index > Fetch the complete documentation index at: https://docs.phoenix.trade/llms.txt > Use this file to discover all available pages before exploring further. # Get trader state > Handles `GET /v1/trader/state/{authority_pubkey}` via `get.v1.trader.state.by_authority_pubkey`. ## OpenAPI ````yaml /openapi/phoenix-public-api.json get /v1/trader/state/{authority_pubkey} openapi: 3.1.0 info: title: Phoenix Eternal API description: >- RESTful API for accessing Phoenix Eternal perpetual trading data. Provides real-time orderbook levels, asset information, and market metadata. termsOfService: https://www.phoenix.trade/terms-of-service contact: name: Phoenix Development Team url: https://github.com/Ellipsis-Labs/phoenix license: name: Proprietary version: 1.0.0 servers: - url: https://perp-api.phoenix.trade description: Phoenix Eternal Perp API security: [] tags: - name: Auth description: Wallet and session authentication. - name: Exchange description: Exchange, market, candle, and no-referral register-instruction workflows. - name: Invite description: Invite validation, referral activation, and wallet allowlist checks. - name: Notifications description: Trader notification reads and acknowledgement helpers. - name: Trader description: Trader state, account history, and transaction builders. externalDocs: url: https://docs.phoenix.trade description: Phoenix developer documentation paths: /v1/trader/state/{authority_pubkey}: get: tags: - Trader summary: Get trader state description: >- Handles `GET /v1/trader/state/{authority_pubkey}` via `get.v1.trader.state.by_authority_pubkey`. operationId: get.v1.trader.state.by_authority_pubkey parameters: - name: traderPdaIndex in: query description: Optional trader PDA index under the authority. required: false schema: type: integer format: int32 minimum: 0 - name: authority_pubkey in: path required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TraderStateSnapshotResponse' security: - PhoenixBearerAuth: [] components: schemas: TraderStateSnapshotResponse: type: object description: REST response wrapper for a trader-state snapshot. required: - authority - traderPdaIndex - slot - slotIndex - snapshot properties: authority: type: string description: Trader authority public key. slot: type: integer format: int64 description: Solana slot for this snapshot. minimum: 0 slotIndex: type: integer format: int32 description: Slot-local index used for deterministic ordering. minimum: 0 snapshot: $ref: '#/components/schemas/TraderStateSnapshot' description: Full trader-state snapshot. traderPdaIndex: type: integer format: int32 description: Trader PDA index under the authority. minimum: 0 TraderStateSnapshot: type: object description: Snapshot payload covering every subaccount belonging to a trader PDA. required: - version - capabilities - makerFeeOverrideMultiplier - takerFeeOverrideMultiplier - subaccounts properties: capabilities: $ref: '#/components/schemas/TraderStateCapabilities' description: >- Trader capability flags and derived views (shared across subaccounts). makerFeeOverrideMultiplier: type: number format: double description: >- Maker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium). subaccounts: type: array items: $ref: '#/components/schemas/TraderStateSubaccountSnapshot' description: Per-subaccount snapshots for this trader PDA. takerFeeOverrideMultiplier: type: number format: double description: >- Taker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium). version: type: integer format: int32 description: Snapshot schema version. minimum: 0 TraderStateCapabilities: type: object description: |- Trader capability flags for a subaccount along with convenient derived views. required: - flags - state - capabilities properties: capabilities: $ref: '#/components/schemas/TraderCapabilitiesView' description: Derived capability booleans. flags: $ref: '#/components/schemas/TraderCapabilityFlags' description: Raw trader capability bitflags. state: $ref: '#/components/schemas/TraderActivityStateView' description: Derived trader activity state. TraderStateSubaccountSnapshot: type: object description: >- Complete subaccount view contained in a snapshot. Snapshot of a single subaccount in the `traderState` channel. Captures collateral plus the latest known rows for every resource while also surfacing the per-subaccount sequence watermark so clients can detect drift. required: - subaccountIndex - sequence - collateral properties: capabilities: oneOf: - type: 'null' - $ref: '#/components/schemas/TraderStateCapabilities' description: >- Trader capability flags and derived views. Optional for backwards compatibility. collateral: type: string description: Collateral balance (human-readable decimal string). cooldownStatus: oneOf: - type: 'null' - $ref: '#/components/schemas/CooldownStatus' description: >- Withdrawal cooldown status. Optional for backwards compatibility. orders: type: array items: $ref: '#/components/schemas/TraderStateLimitOrderEvent' description: Limit-order rows grouped by symbol. positions: type: array items: $ref: '#/components/schemas/TraderStatePositionSnapshot' description: Position rows keyed by symbol. sequence: type: integer format: int64 description: Monotonic sequence for subaccount state updates. minimum: 0 splines: type: array items: $ref: '#/components/schemas/TraderStateSplineSnapshot' description: Spline rows grouped by symbol. subaccountIndex: type: integer format: int32 description: Subaccount index under the trader PDA. minimum: 0 triggers: type: array items: $ref: '#/components/schemas/TraderStateTriggerSnapshot' description: Trigger rows grouped by symbol (TP/SL and conditional triggers). TraderCapabilitiesView: type: object description: |- Capability matrix exposed alongside a trader's status. Each field is a nested object that reports whether the action is immediately available (`immediate`) and whether it becomes available after activating a cold trader (`viaColdActivation`). required: - placeLimitOrder - placeMarketOrder - riskIncreasingTrade - riskReducingTrade - depositCollateral - withdrawCollateral properties: depositCollateral: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to deposit collateral. placeLimitOrder: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to place limit orders. placeMarketOrder: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to place market orders. riskIncreasingTrade: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to execute risk-increasing trades. riskReducingTrade: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to execute risk-reducing trades. withdrawCollateral: $ref: '#/components/schemas/CapabilityAccessView' description: Capability to withdraw collateral. TraderCapabilityFlags: type: integer format: int32 description: >- Canonical capability mask stored in every trader header. The derived preset constructors (`cold`, `hot_active`, `reduce_only`, `frozen`) preserve the intended behavioural guarantees: cold traders operate from their local buffer until warmed, active traders have full matching-engine access, reduce-only traders may only take risk-reducing actions (but can still move collateral), and frozen traders are fully quarantined with balance transfers disabled. minimum: 0 TraderActivityStateView: type: string description: Serializable representation of a trader's high-level activity state. enum: - uninitialized - cold - active - reduceOnly - frozen CooldownStatus: type: object description: >- Withdrawal cooldown status for a trader PDA. Indicates whether the trader can withdraw based on the time elapsed since their last deposit. This applies at the PDA level (main account), not per-subaccount. Clients should compute withdrawal eligibility as: `canWithdraw = (currentSlot >= lastDepositSlot + cooldownPeriodInSlots) && capabilities.withdraw` required: - lastDepositSlot - cooldownPeriodInSlots properties: cooldownPeriodInSlots: type: integer format: int64 description: Number of slots required to wait after a deposit before withdrawing. minimum: 0 lastDepositSlot: type: integer format: int64 description: Slot when the trader last deposited collateral. minimum: 0 TraderStateLimitOrderEvent: type: object description: Order grouping used for snapshots. required: - symbol - orders properties: orders: type: array items: $ref: '#/components/schemas/TraderStateMarketLimitOrderEvent' description: Orders currently associated with the symbol. symbol: type: string description: Market symbol for this order group. TraderStatePositionSnapshot: allOf: - $ref: '#/components/schemas/TraderStatePositionRow' description: Position row values for the symbol. - type: object required: - symbol properties: symbol: type: string description: Market symbol for this position row. description: >- Snapshot entry keyed by market symbol. Flattened position entry keyed by market symbol. Used by snapshots so clients can store each symbol's latest values without dealing with nested arrays. TraderStateSplineSnapshot: allOf: - $ref: '#/components/schemas/TraderStateSplineRow' description: Spline row values for the symbol. - type: object required: - symbol properties: symbol: type: string description: Market symbol for this spline row. description: Spline snapshot grouped by market symbol. TraderStateTriggerSnapshot: allOf: - $ref: '#/components/schemas/TraderStateTriggerRow' description: Trigger rows for the symbol. - type: object required: - symbol properties: symbol: type: string description: Market symbol for this trigger group. description: >- Trigger snapshot grouped by market symbol. Top-level subaccount entry containing all TP/SL and conditional triggers for a single market. This is the canonical location for trigger data; the trigger fields still present on `TraderStatePositionRow` are deprecated. CapabilityAccessView: type: object description: >- Capability exposure for the current trader state. `immediate` indicates the action can be taken without additional state transitions, while `via_cold_activation` signals the action will succeed if the trader warms from `InitializedCold` to `InitializedHot` during processing. required: - immediate properties: immediate: type: boolean description: Whether this capability is currently available. viaColdActivation: type: boolean description: Whether this capability becomes available after cold activation. TraderStateMarketLimitOrderEvent: type: object description: |- Detailed limit order representation. Wire representation of a single limit-order row grouped by symbol. required: - orderSequenceNumber - side - orderType - priceTicks - priceUsd - sizeRemainingLots - initialSizeLots - reduceOnly - status properties: change: oneOf: - type: 'null' - $ref: '#/components/schemas/TraderStateRowChangeKind' description: Row-level change kind for delta payloads. conditionalKind: type: - string - 'null' description: Conditional order kind when present. initialSizeLots: type: string description: Initial order size in lots. isConditionalOrder: type: boolean description: Whether this order originated from a conditional trigger. isStopLoss: type: boolean description: Whether this order is a stop-loss order. isStopLossDirection: type: boolean description: Whether this TP/SL order uses stop-loss direction. orderSequenceNumber: type: string description: Order sequence number. orderType: type: string description: Order type (for example, limit/market variants). priceTicks: type: string description: Price in ticks. priceUsd: type: string description: Price in USD (decimal string). reduceOnly: type: boolean description: Whether the order is reduce-only. side: $ref: '#/components/schemas/Side' description: Side of the order. sizeRemainingLots: type: string description: Remaining order size in lots. status: type: string description: Current order status. TraderStatePositionRow: type: object description: Position row used for snapshots and deltas. required: - positionSequenceNumber - basePositionLots - entryPriceTicks - entryPriceUsd - virtualQuotePositionLots - unsettledFundingQuoteLots - accumulatedFundingQuoteLots - takeProfitTriggers - stopLossTriggers properties: accumulatedFundingQuoteLots: type: string description: Accumulated funding amount in quote lots (signed decimal string). basePositionLots: type: string description: Base position size in lots (signed decimal string). conditionalStopLossTriggers: type: array items: $ref: '#/components/schemas/TraderStateConditionalStopLossTrigger' description: Configured conditional stop-loss triggers. conditionalTakeProfitTriggers: type: array items: $ref: '#/components/schemas/TraderStateConditionalTakeProfitTrigger' description: Configured conditional take-profit triggers. entryPriceTicks: type: string description: Entry price in ticks. entryPriceUsd: type: string description: Entry price in USD (decimal string). positionSequenceNumber: type: string description: Position sequence number used for ordering/versioning. stopLossTriggers: type: array items: $ref: '#/components/schemas/TraderStateStopLossTrigger' description: Configured stop-loss triggers. takeProfitTriggers: type: array items: $ref: '#/components/schemas/TraderStateTakeProfitTrigger' description: Configured take-profit triggers. unsettledFundingQuoteLots: type: string description: Unsettled funding amount in quote lots (signed decimal string). virtualQuotePositionLots: type: string description: Virtual quote position in lots (signed decimal string). TraderStateSplineRow: type: object description: Spline row containing the spline parameters and fill state. required: - midPriceTicks - bidFilledAmountLots - askFilledAmountLots properties: askFilledAmountLots: type: string description: Total filled ask amount in lots. askRegions: type: array items: $ref: '#/components/schemas/TraderStateTickRegion' description: Ask-side spline regions. bidFilledAmountLots: type: string description: Total filled bid amount in lots. bidRegions: type: array items: $ref: '#/components/schemas/TraderStateTickRegion' description: Bid-side spline regions. midPriceTicks: type: string description: Mid price in ticks. TraderStateTriggerRow: type: object description: All trigger data for a single market symbol. required: - takeProfitTriggers - stopLossTriggers properties: conditionalStopLossTriggers: type: array items: $ref: '#/components/schemas/TraderStateConditionalStopLossTrigger' description: Configured conditional stop-loss triggers. conditionalTakeProfitTriggers: type: array items: $ref: '#/components/schemas/TraderStateConditionalTakeProfitTrigger' description: Configured conditional take-profit triggers. stopLossTriggers: type: array items: $ref: '#/components/schemas/TraderStateStopLossTrigger' description: Configured stop-loss triggers. takeProfitTriggers: type: array items: $ref: '#/components/schemas/TraderStateTakeProfitTrigger' description: Configured take-profit triggers. TraderStateRowChangeKind: type: string description: Change indicator used for row-level deltas. enum: - updated - closed Side: type: string enum: - bid - ask TraderStateConditionalStopLossTrigger: type: object description: Conditional stop-loss trigger rows scoped to a position. required: - conditionalStopLossId - trigger - status properties: conditionalStopLossId: type: string description: Conditional stop-loss trigger identifier. status: type: string description: Trigger status. trigger: $ref: '#/components/schemas/TraderStateConditionalTrigger' description: Trigger configuration and conditional metadata. TraderStateConditionalTakeProfitTrigger: type: object description: Conditional take-profit trigger rows scoped to a position. required: - conditionalTakeProfitId - trigger - status properties: conditionalTakeProfitId: type: string description: Conditional take-profit trigger identifier. status: type: string description: Trigger status. trigger: $ref: '#/components/schemas/TraderStateConditionalTrigger' description: Trigger configuration and conditional metadata. TraderStateStopLossTrigger: type: object description: Stop-loss trigger rows scoped to a position. required: - stopLossId - trigger - status properties: status: type: string description: Trigger status. stopLossId: type: string description: Stop-loss trigger identifier. trigger: $ref: '#/components/schemas/TraderStateTrigger' description: Trigger configuration. TraderStateTakeProfitTrigger: type: object description: Take-profit trigger rows scoped to a position. required: - takeProfitId - trigger - status properties: status: type: string description: Trigger status. takeProfitId: type: string description: Take-profit trigger identifier. trigger: $ref: '#/components/schemas/TraderStateTrigger' description: Trigger configuration. TraderStateTickRegion: type: object description: Tick region for spline configuration. required: - startPriceTicks - endPriceTicks - densityLotsPerTick - totalSizeLots - filledSizeLots properties: densityLotsPerTick: type: string description: Density in lots per tick. endPriceTicks: type: string description: End price of the region in ticks. filledSizeLots: type: string description: Filled region size in lots. startPriceTicks: type: string description: Start price of the region in ticks. totalSizeLots: type: string description: Total region size in lots. TraderStateConditionalTrigger: allOf: - $ref: '#/components/schemas/TraderStateTrigger' description: Base trigger configuration. - type: object required: - maxSizeLots - fillableSizeLots - filledSizeLots - usePercent - percent properties: attachedOrderSequenceNumber: type: - string - 'null' description: Attached order sequence number when present. fillableSizeLots: type: string description: Remaining fillable trigger size in base lots. filledSizeLots: type: string description: Filled trigger size in base lots. maxSizeLots: type: string description: Max trigger size in base lots. percent: type: integer format: int32 description: Percentage used when `use_percent` is true. minimum: 0 usePercent: type: boolean description: Whether trigger sizing uses a percentage of margin. description: Trigger configuration for conditional trigger orders. TraderStateTrigger: type: object description: Trigger configuration for TP/SL orders. required: - triggerPriceTicks - executionPriceTicks - side - kind properties: executionPriceTicks: type: string description: Execution price in ticks when the trigger fires. kind: $ref: '#/components/schemas/StopLossOrderKind' description: Stop-loss order kind. side: $ref: '#/components/schemas/Side' description: Order side for the trigger. triggerPriceTicks: type: string description: Trigger price in ticks. StopLossOrderKind: type: string enum: - ioc - limit securitySchemes: PhoenixBearerAuth: type: http scheme: bearer description: Bearer access token issued by `/v1/auth/*` login endpoints. ````