Overview
Positions gives platforms and their participants a real-time, net view of digital asset and fiat holdings derived from trade activity, without having to reconstruct balances from raw trade data themselves. As trades move through their lifecycle, zerohash continuously recalculates each participant's net position per asset and exposes it through a single, simplified endpoint set. A platform can view its own positions, drill into any one participant, or pull every participant's positions across the platform in one call.
Use Cases
Common applications include:
- Self-service position monitoring for exchange-style platforms tracking their own net exposure per asset.
- End-customer position views, where a participant sees their holdings.
- Platform-wide oversight, where a platform retrieves all of its participants' positions in a single view for risk, treasury, or support.
- Reconciliation, tying a net position back to the individual trades that produced it before settlement.
Key Concepts
Positions are derived from trades, not settled balances. A position is the running net of a participant's trade activity in a given asset. It is not the same as a settled, withdrawable balance. For settled ledger state, use the Accounts and Balances endpoints. Use Positions when you want net exposure implied by trades, including trades that have not yet settled.
Positions are calculated across trade states. zerohash tracks each trade's trade_state (accepted, active, terminated) and maintains three parallel net figures per asset, so you can choose the view that matches your use case:
| View | Includes | Meaning |
|---|---|---|
position_accepted_trades_only | Trades in accepted | Settlement has not yet been attempted |
position_active_trades_only | Trades in active | Settlement was attempted but not yet successful |
position_all_open_trades | accepted + active | Net of all open trades |
Positions are signed. Values can be negative. A negative asset position means net short (net delivered) in that asset; a negative fiat position means net fiat owed. For example, a participant who buys 1 BTC for USD shows a positive BTC position and a negative USD position.
Positions update asynchronously. As trade states change (accepted → active → terminated), the affected positions recalculate. A newly submitted trade appears once it reaches accepted, and drops out of the open figures once terminated.
The Position Resource
| Field | Type | Description |
|---|---|---|
platform_code | string | The platform the position belongs to |
participant_code | string | The participant the position belongs to |
account_label | string | The account label holding the position |
asset | string | The asset code, e.g. BTC, USD |
position_all_open_trades | string | Net position across all open trades (trade_state of accepted or active) |
position_accepted_trades_only | string | Net position across trades in accepted (settlement not yet attempted) |
position_active_trades_only | string | Net position across trades in active (settlement attempted, not yet successful) |
trade_ids_list | array of strings | Trade IDs (from /trades) contributing to this position |
Key Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /positions | List positions for the authenticated participant |
| GET | /positions/platform/{platform_code} | List all positions across a platform's participants |
| GET | /positions/participant/{participant_code} | List positions for a specific participant |
Responses are wrapped in a message array, with one object per platform_code / participant_code / account_label / asset combination.
Filtering
platform_code(query) scopes results to a single platform.account_label(query) scopes results to a single account label, e.g.general.- On the platform endpoint,
participant_codecan be supplied multiple times to filter to a set of participants.
Best Practices
- Use
trade_ids_listto reconcile any position back to the individual trades in/trades. - Treat all position values as decimal strings and parse with a decimal-safe type; do not use floating point.
- For settled, withdrawable balances, use Accounts and Balances rather than Positions.
- Scope large responses with
platform_codeandaccount_labelfilters.
Authentication
All requests require the standard HMAC headers: X-SCX-SIGNED (base64-encoded HMAC-SHA256 signature) and X-SCX-TIMESTAMP (Unix seconds, within 60 seconds of server time). See the Authentication guide.