Positions and balances

Positions and balances

Introduction

Using Vega’s APIs, you can track collateral balances (also known as collateral accounts in Vega queries), as well as view information about your positions, such as the profit and loss on trades.

There are several different types of accounts on Vega, each specific to how the collateral is accessed and managed:

  • INSURANCE
    Insurance accounts are available and show the total amount of collateral currently held in the insurance pool.
  • MARGIN
    Margin accounts are available when a position is open on a market for a party. Please see the section on margins for more information.
  • GENERAL
    General accounts are where undeployed collateral is held, ready to be deployed on a market by trading or used for governance.
  • SETTLEMENT
    Accounts used during the settlement process only.

There are two types of scope for accounts, market or party based, where market scope is related to balances for a specific market, and party scope is related to balances for a specific party (public key).

In order to track your account balances and positions on Vega there are several APIs available:

Listing collateral accounts for a party (public key)

Connect to a Vega API server, and request accounts for a party:

Note: account balances of any party for which a public key is known can be publicly listed on Vega.

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

See also REST API reference for further query detail.

Make sure vegaapiclient is installed (from PyPI):

pip install --upgrade Vega-API-client

This Python snippet code shows how to query for a list of orders on a market:

See also gRPC API reference for further query detail.

If successful, the response will include:

Field Description
accounts A list of zero or more accounts for the party specified. Balances use decimal place values specified by the asset, e.g. 5 decimal places. A party will have one GENERAL account and MARGIN account for each market where they have an open position. Governance assets will also be listed as GENERAL accounts, e.g. VOTE.
For full example code, please visit the repo on GitHub.

This request has additional (optional) request filter parameters for market identifier, type and asset. Specifying a market will return only accounts related to a particular market and an empty list if the market is not found. Specifying the type will return only accounts related to a particular type e.g. INSURANCE, and specifying an asset will return accounts relating to a particular asset. Please see the API reference documentation for the API for exact details.

Listing collateral accounts for a market

Connect to a Vega API server, and request accounts for a market:

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

See also REST API reference for further query detail.

Make sure vegaapiclient is installed (from PyPI):

pip install --upgrade Vega-API-client

This Python snippet code shows how to query for a list of orders for a party:

See also gRPC API reference for further query detail.

If successful, the response will include:

Field Description
accounts A list of zero or more accounts for the market specified. Balances use decimal place values specified by the asset, e.g. 5 decimal places.
For full example code, please visit the repo on GitHub.

Similar to querying for accounts for a party, this request has an additional (optional) request filter parameter for asset. Specifying an asset will return only accounts related to a particular asset and an empty list if the market is not found. Please see the API reference documentation for the API for exact details.

Listing positions for a party (public key)

Positions requests return key information such as realised and unrealised profit and loss (PNL), current open volume, etc.

Connect to a Vega API server, and request positions for a party:

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

See also REST API reference for further query detail.

Make sure vegaapiclient is installed (from PyPI):

pip install --upgrade Vega-API-client

This Python snippet code shows how to query for a list of trades for an order:

See also gRPC API reference for further query detail.

If successful, the response will include:

Field Description
positions A list of zero or more positions for the party specified. Each position will include a reference to the related market and the timestamp for when the values were last updated.
For full example code, please visit the repo on GitHub.

What’s next?