Positions

const response = await client.request({
  id: ctx.id,
  epoch: ctx.epoch,
  expiresAt: ctx.expiresAt,
  command: {
    kind: 'read',
    query: { family: 'positions', limit: 32 },
  },
});

({
  kind: 'page',
  family: 'positions',
  revision: snapshotRevision,
  next: new Uint8Array(40),
  evaluatedAt: observedAt,
  rows: [
    { kind: 'position', market: ctx.market, precision: 1, lots: 2n, basis: 200n },
  ],
})

({ kind: 'error', code: 'conflict' })

const response = await client.request({
  id: ctx.id,
  epoch: ctx.epoch,
  expiresAt: ctx.expiresAt,
  command: {
    kind: 'read',
    query: { family: 'positions', limit: 32 },
  },
});

({
  kind: 'page',
  family: 'positions',
  revision: snapshotRevision,
  next: new Uint8Array(40),
  evaluatedAt: observedAt,
  rows: [
    { kind: 'position', market: ctx.market, precision: 1, lots: 2n, basis: 200n },
  ],
})

({ kind: 'error', code: 'conflict' })

Carrier: POST /v1/exchange (encrypted binary). Read family: positions · Permission: owner or current READ agent. Private positions, signed basis and optional mark and leverage. Results are private to the bound account. The same query is available over HTTP and WebSocket, including subscriptions.

These are signed SDK fields and decoded results, not a plaintext JSON HTTP body. The shared carrier accepts encrypted application/octet-stream.

const response = await client.request({
  id: ctx.id,
  epoch: ctx.epoch,
  expiresAt: ctx.expiresAt,
  command: {
    kind: 'read',
    query: { family: 'positions', limit: 32 },
  },
});

({
  kind: 'page',
  family: 'positions',
  revision: snapshotRevision,
  next: new Uint8Array(40),
  evaluatedAt: observedAt,
  rows: [
    { kind: 'position', market: ctx.market, precision: 1, lots: 2n, basis: 200n },
  ],
})

({ kind: 'error', code: 'conflict' })

Request fields

Use the configured client and envelope. Each request supplies id, current epoch and authentication expiresAt, as shown in the example.

"read"

required

Read-command discriminator.

"positions"

required

Selects this exact private projection.

number

required

Integer from 1 to 64 rows. The example requests 32.

Uint8Array (40 bytes)

Omit or use all-zero bytes to start. For another page, use the prior page’s next under the same snapshot revision.

Response fields

Illustrative decoded SDK values are shown at the right; absent optional fields mean unavailable, not zero. Empty rows is valid.

"page"

required

Paged-response discriminator.

"positions"

required

The requested family.

Uint8Array (32 bytes)

required

Commitment to the permitted snapshot and query identity, not a global activity counter.

Uint8Array (40 bytes)

required

Next cursor; all-zero means no more retained rows.

bigint (u64)

required

Qualified Cinder evaluation time, in milliseconds.

ReadRow[]

required

At most the requested limit.

Show Positions row fields

"position"

required

Position-row discriminator.

Uint8Array (32 bytes)

required

Configured market ID.

number (u32)

required

Market precision version, not decimal places.

bigint (i64)

required

Signed remaining lots: positive long, negative short.

bigint (i128)

required

Signed remaining entry value in quote atoms, not a displayed average price.

Valuation

Optional qualified mark and unrealized PnL.

Show valuation fields

bigint (u64)

required

Qualified positive mark, in ticks.

bigint (i128)

required

Unrealized PnL, in quote atoms.

Leverage

Optional qualified policy cap and selected leverage.

Show leverage fields

bigint (u64)

required

Maximum multiplier scaled by 10,000.

bigint (u64)

required

Selected multiplier scaled by 10,000; does not exceed cap.

Behavior

Includes flat configured markets. Missing valuation or leverage is not zero. Remaining basis is not displayed average price. This is not an isolated-margin switch or a separate native account.

Paging and errors

Read queries do not change financial state or consume order budgets. Permissions filter rows before paging. Changed permitted rows return encrypted conflict; restart at zero instead of combining revisions. End-of-pages covers retained rows, not complete external venue history. See paging, errors, limits and availability. A disconnected subscription needs fresh attestation, current authority and a replacement snapshot.

Overview

Commands

Private reads

WebSocket

Request fields

Response fields

Behavior

Paging and errors

​Request fields

​Response fields

​Behavior

​Paging and errors

Request fields

Response fields

Behavior

Paging and errors