Building blocks
While there are hundreds of available endpoints, the categories below cover the basics to get you started with understanding what you need to interact with Vega.
Parties
A party is a single user, defined as a Vega public key. As one person or entity can have many public keys, this is a unique identifier as far as an individual key's actions. Party ID and public key (pubkey) are all names for the same thing.
| Description | Documentation | Call |
|---|---|---|
| See a paginated list of parties | List parties | GET /api/v2/parties |
Assets
Assets used on Vega (to start) are all ERC-20 tokens, and thus originate on the Ethereum chain, not the Vega chain. Inter-chain asset interactions between Vega and Ethereum are facilitated through the Ethereum bridges.
Assets can only be added to the network to be used as collateral through a successful governance proposal and enactment, and a follow-on update to the asset bridge.
| Description | Documentation | Call |
|---|---|---|
| See all assets that can be used on the network | List assets | GET /api/v2/assets |
| Show a specific asset's details | Asset | GET /api/v2/asset/:assetId |
Deposits and withdrawals
Assets used on the Vega network need to be deposited from an Ethereum wallet using the bridge contracts, and can be withdrawn back into an Ethereum wallet if they are not being used for margin or positions.
| Description | Documentation | Call |
|---|---|---|
| See all deposits for a specific public key | List deposits | GET /api/v2/deposits |
| See a specific deposit using its ID | Deposit | GET /api/v2/deposit/:id |
| Understanding the concepts: accounts | Accounts | |
| Understanding the concepts: deposits and withdrawals | Deposits and withdrawals |
Accounts
Vega relies on accounts to ensure funds are never lost or double spent. The amounts in each account, as well as the transactions that were added to and removed from those accounts, are all recorded and stored on-chain. Accounts are used either to hold assets that the public key holder is in control of using — such as deposited collateral, or for setting money aside that only the network can manage — to fulfil margin requirements, for example, or to store assets that are earmarked for rewards or paying out fees.
| Description | Documentation | Call |
|---|---|---|
| List accounts based on chosen filters | List accounts | GET /api/v2/accounts |
| Understanding the concepts: accounts | Accounts |
Markets
Markets have accounts, are created with proposals, and allow parties to place orders with assets.
| Description | Documentation | Call |
|---|---|---|
| See all markets on the network | List markets | GET /api/v2/markets |
| Get information about a single market using the market's ID | Market | GET /api/v2/market/:marketId |
| List the latest data for every market | Markets data | GET /api/v2/markets/data |
| Understanding the concepts: market lifecycle | Market lifecycle |
Orders and positions
An order is an instruction to buy or sell on a specific market, and it can go long or short on the market's price. Placing an order does not guarantee it gets filled, but if it is filled, it will result in a position, which will require collateral to use for margin to keep that position open.
| Description | Documentation | Call |
|---|---|---|
| Get information about an order using its ID | Order | GET /api/v2/order/:orderId |
| Get a list of orders that have been filtered based on information you provide | List orders | GET /api/v2/orders |
| Get a list of all positions for a specific party ID | List positions | GET /api/v2/positions |
| Get a paginated list of all trades, optionally filtered by party, market, or order | List trades | GET /api/v2/trades |
| Understand the concepts: orders | Orders | |
| Understand the concepts: positions | Positions |
Governance proposals and voting
Governance proposals used to add new assets and markets, as well as to suggest changes to assets, markets, and network parameters, as well as off-chain suggestions. VEGA tokens need to be associated to the Vega public key that wants to take part in governance.
| Description | Documentation | Call |
|---|---|---|
| View all governance proposals with their current state, paginated | List proposals | GET /api/v2/governances |
| Get detailed information about a specific governance proposal using its ID | Proposal | GET /api/v2/governance |
| How to submit proposals using command line | Submitting proposals | |
| Understanding the concepts: Governance | Vega governance |
Governance token
VEGA token are used for taking part in network, market, asset and freeform governance, and to secure the network by nominating validators that run the network.
| Description | Documentation | Call |
|---|---|---|
| See a list of votes | List votes | GET /api/v2/votes |
| How to nominate validators using the smart contracts | Stake tokens | |
| Understand the concepts: Governance | Vega governance |