--- title: "Get trader state" method: GET path: "/v1/trader/state/{authority_pubkey}" tags: ["Trader"] --- # Get trader state `GET /v1/trader/state/{authority_pubkey}` Handles `GET /v1/trader/state/{authority_pubkey}` via `get.v1.trader.state.by_authority_pubkey`. ## Path parameters - `authority_pubkey` string, required ## Query parameters - `traderPdaIndex` integer ## Response `200` - TraderStateSnapshotResponse — REST response wrapper for a trader-state snapshot. - `authority` string, required — Trader authority public key. - `slot` integer, required — Solana slot for this snapshot. - `slotIndex` integer, required — Slot-local index used for deterministic ordering. - `snapshot` TraderStateSnapshot, required — Snapshot payload covering every subaccount belonging to a trader PDA. - `capabilities` TraderStateCapabilities, required — Trader capability flags for a subaccount along with convenient derived views. - `capabilities` TraderCapabilitiesView, required — 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`). - `depositCollateral` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `placeLimitOrder` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `placeMarketOrder` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `riskIncreasingTrade` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `riskReducingTrade` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `withdrawCollateral` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `flags` integer, required — 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. - `state` 'uninitialized' | 'cold' | 'active' | 'reduceOnly' | 'frozen', required — Serializable representation of a trader's high-level activity state. - `makerFeeOverrideMultiplier` number, double, required — Maker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium). - `subaccounts` TraderStateSubaccountSnapshot[], required — Per-subaccount snapshots for this trader PDA. - `capabilities` TraderStateCapabilities — Trader capability flags for a subaccount along with convenient derived views. - `capabilities` TraderCapabilitiesView, required — 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`). - `depositCollateral` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `placeLimitOrder` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `placeMarketOrder` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `riskIncreasingTrade` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `riskReducingTrade` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `withdrawCollateral` CapabilityAccessView, required — 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. - `immediate` boolean, required — Whether this capability is currently available. - `viaColdActivation` boolean — Whether this capability becomes available after cold activation. - `flags` integer, required — 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. - `state` 'uninitialized' | 'cold' | 'active' | 'reduceOnly' | 'frozen', required — Serializable representation of a trader's high-level activity state. - `collateral` string, required — Collateral balance (human-readable decimal string). - `cooldownStatus` CooldownStatus — 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` - `cooldownPeriodInSlots` integer, required — Number of slots required to wait after a deposit before withdrawing. - `lastDepositSlot` integer, required — Slot when the trader last deposited collateral. - `orders` TraderStateLimitOrderEvent[] — Limit-order rows grouped by symbol. - `orders` TraderStateMarketLimitOrderEvent[], required — Orders currently associated with the symbol. - `change` 'updated' | 'closed' — Change indicator used for row-level deltas. - `conditionalKind` string, nullable — Conditional order kind when present. - `initialSizeLots` string, required — Initial order size in lots. - `isConditionalOrder` boolean — Whether this order originated from a conditional trigger. - `isStopLoss` boolean — Whether this order is a stop-loss order. - `isStopLossDirection` boolean — Whether this TP/SL order uses stop-loss direction. - `orderSequenceNumber` string, required — Order sequence number. - `orderType` string, required — Order type (for example, limit/market variants). - `priceTicks` string, required — Price in ticks. - `priceUsd` string, required — Price in USD (decimal string). - `reduceOnly` boolean, required — Whether the order is reduce-only. - `side` 'bid' | 'ask', required - `sizeRemainingLots` string, required — Remaining order size in lots. - `status` string, required — Current order status. - `symbol` string, required — Market symbol for this order group. - `positions` TraderStatePositionSnapshot[] — Position rows keyed by symbol. - `accumulatedFundingQuoteLots` string, required — Accumulated funding amount in quote lots (signed decimal string). - `basePositionLots` string, required — Base position size in lots (signed decimal string). - `conditionalStopLossTriggers` TraderStateConditionalStopLossTrigger[] — Configured conditional stop-loss triggers. - `conditionalStopLossId` string, required — Conditional stop-loss trigger identifier. - `status` string, required — Trigger status. - `trigger` TraderStateConditionalTrigger, required — Trigger configuration for conditional trigger orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `attachedOrderSequenceNumber` string, nullable — Attached order sequence number when present. - `fillableSizeLots` string, required — Remaining fillable trigger size in base lots. - `filledSizeLots` string, required — Filled trigger size in base lots. - `maxSizeLots` string, required — Max trigger size in base lots. - `percent` integer, required — Percentage used when `use_percent` is true. - `usePercent` boolean, required — Whether trigger sizing uses a percentage of margin. - `conditionalTakeProfitTriggers` TraderStateConditionalTakeProfitTrigger[] — Configured conditional take-profit triggers. - `conditionalTakeProfitId` string, required — Conditional take-profit trigger identifier. - `status` string, required — Trigger status. - `trigger` TraderStateConditionalTrigger, required — Trigger configuration for conditional trigger orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `attachedOrderSequenceNumber` string, nullable — Attached order sequence number when present. - `fillableSizeLots` string, required — Remaining fillable trigger size in base lots. - `filledSizeLots` string, required — Filled trigger size in base lots. - `maxSizeLots` string, required — Max trigger size in base lots. - `percent` integer, required — Percentage used when `use_percent` is true. - `usePercent` boolean, required — Whether trigger sizing uses a percentage of margin. - `entryPriceTicks` string, required — Entry price in ticks. - `entryPriceUsd` string, required — Entry price in USD (decimal string). - `positionSequenceNumber` string, required — Position sequence number used for ordering/versioning. - `stopLossTriggers` TraderStateStopLossTrigger[], required — Configured stop-loss triggers. - `status` string, required — Trigger status. - `stopLossId` string, required — Stop-loss trigger identifier. - `trigger` TraderStateTrigger, required — Trigger configuration for TP/SL orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `takeProfitTriggers` TraderStateTakeProfitTrigger[], required — Configured take-profit triggers. - `status` string, required — Trigger status. - `takeProfitId` string, required — Take-profit trigger identifier. - `trigger` TraderStateTrigger, required — Trigger configuration for TP/SL orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `unsettledFundingQuoteLots` string, required — Unsettled funding amount in quote lots (signed decimal string). - `virtualQuotePositionLots` string, required — Virtual quote position in lots (signed decimal string). - `symbol` string, required — Market symbol for this position row. - `sequence` integer, required — Monotonic sequence for subaccount state updates. - `splines` TraderStateSplineSnapshot[] — Spline rows grouped by symbol. - `askFilledAmountLots` string, required — Total filled ask amount in lots. - `askRegions` TraderStateTickRegion[] — Ask-side spline regions. - `densityLotsPerTick` string, required — Density in lots per tick. - `endPriceTicks` string, required — End price of the region in ticks. - `filledSizeLots` string, required — Filled region size in lots. - `startPriceTicks` string, required — Start price of the region in ticks. - `totalSizeLots` string, required — Total region size in lots. - `bidFilledAmountLots` string, required — Total filled bid amount in lots. - `bidRegions` TraderStateTickRegion[] — Bid-side spline regions. - `densityLotsPerTick` string, required — Density in lots per tick. - `endPriceTicks` string, required — End price of the region in ticks. - `filledSizeLots` string, required — Filled region size in lots. - `startPriceTicks` string, required — Start price of the region in ticks. - `totalSizeLots` string, required — Total region size in lots. - `midPriceTicks` string, required — Mid price in ticks. - `symbol` string, required — Market symbol for this spline row. - `subaccountIndex` integer, required — Subaccount index under the trader PDA. - `triggers` TraderStateTriggerSnapshot[] — Trigger rows grouped by symbol (TP/SL and conditional triggers). - `conditionalStopLossTriggers` TraderStateConditionalStopLossTrigger[] — Configured conditional stop-loss triggers. - `conditionalStopLossId` string, required — Conditional stop-loss trigger identifier. - `status` string, required — Trigger status. - `trigger` TraderStateConditionalTrigger, required — Trigger configuration for conditional trigger orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `attachedOrderSequenceNumber` string, nullable — Attached order sequence number when present. - `fillableSizeLots` string, required — Remaining fillable trigger size in base lots. - `filledSizeLots` string, required — Filled trigger size in base lots. - `maxSizeLots` string, required — Max trigger size in base lots. - `percent` integer, required — Percentage used when `use_percent` is true. - `usePercent` boolean, required — Whether trigger sizing uses a percentage of margin. - `conditionalTakeProfitTriggers` TraderStateConditionalTakeProfitTrigger[] — Configured conditional take-profit triggers. - `conditionalTakeProfitId` string, required — Conditional take-profit trigger identifier. - `status` string, required — Trigger status. - `trigger` TraderStateConditionalTrigger, required — Trigger configuration for conditional trigger orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `attachedOrderSequenceNumber` string, nullable — Attached order sequence number when present. - `fillableSizeLots` string, required — Remaining fillable trigger size in base lots. - `filledSizeLots` string, required — Filled trigger size in base lots. - `maxSizeLots` string, required — Max trigger size in base lots. - `percent` integer, required — Percentage used when `use_percent` is true. - `usePercent` boolean, required — Whether trigger sizing uses a percentage of margin. - `stopLossTriggers` TraderStateStopLossTrigger[], required — Configured stop-loss triggers. - `status` string, required — Trigger status. - `stopLossId` string, required — Stop-loss trigger identifier. - `trigger` TraderStateTrigger, required — Trigger configuration for TP/SL orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `takeProfitTriggers` TraderStateTakeProfitTrigger[], required — Configured take-profit triggers. - `status` string, required — Trigger status. - `takeProfitId` string, required — Take-profit trigger identifier. - `trigger` TraderStateTrigger, required — Trigger configuration for TP/SL orders. - `executionPriceTicks` string, required — Execution price in ticks when the trigger fires. - `kind` 'ioc' | 'limit', required - `side` 'bid' | 'ask', required - `triggerPriceTicks` string, required — Trigger price in ticks. - `symbol` string, required — Market symbol for this trigger group. - `takerFeeOverrideMultiplier` number, double, required — Taker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium). - `version` integer, required — Snapshot schema version. - `traderPdaIndex` integer, required — Trader PDA index under the authority. --- [API](https://skmtc.net/phoenix/apis/phoenix-eternal-api.md) · [All operations](https://skmtc.net/phoenix/apis/phoenix-eternal-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phoenix/phoenix-eternal-api/versions/0f598402d680/schema)