API tips

Resources: Developing

This section is part of a series on the topic of Development.

Docs:

• API tips and help
• Useful endpoints
• Websocket streams
• Software release summaries

Other resources:

• See the code on GitHub ↗

Connecting to the APIs

As most of the APIs are designed to be used for trading-related queries, the best place to try them out is on the testnet network, also known as Fairground.

To use the Vega APIs, a developer will need access to a network-compatible instance of the relevant software, depending on their goals: core node, data node, and/or Vega Wallet.

Mainnet: Consensus validators may provide public servers for accessing the mainnet APIs, however that does not mean they should be relied upon for constant uptime and full access to all APIs. Each Vega Wallet release for mainnet wallet is pre-configured with any publicly announced nodes at the time of release.

Validator testnet: Some consensus validators may provide public servers for accessing the APIs on the validator testnet network, however that does not mean they should be relied on for constant uptime or full access to APIs.

Fairground: The project team operate a number of data nodes with publicly available endpoints for the Vega-run testnet, called Fairground. Each Fairground wallet app release is pre-configured with known nodes, including those operated by the project team, at the time of release.

Rate limiting

Some rate limiting is implemented with default limitations on the APIs.

For the specifics on WebSocket connections, see WebSocket streams page.

Data node operators can limit the rate of API requests. Rate limiting is applied on a per-remote-IP-address basis.

Each IP address that connects to a data node is assigned a bucket of tokens. That bucket has a maximum capacity, and begins full of tokens. Each API request costs one token, which is removed from the bucket when the call is made. The data node adds a number of tokens every second (the rate of the limiter) to the bucket up to its maximum capacity.

On average over time, this enforces the average rate of API requests to not exceed rate requests/second. It also allows temporary periods of more intensive use; the maximum rate being to use the entire capacity of the bucket within one second.

Clients can use the IETF-RFC compliant-headers to see their rate limiting status. (Read about the IETF RFC standards↗.

It's implemented with the following headers in each API response:

• RateLimit-Limit The maximum request limit within the time window (1s)
• RateLimit-Reset The rate-limiter time window duration in seconds (always 1s)
• RateLimit-Remaining The remaining tokens

Upon rejection, the following HTTP response headers are available:

• X-Rate-Limit-Limit The maximum request limit
• X-Rate-Limit-Duration The rate-limiter duration
• X-Rate-Limit-Request-Forwarded-For The rejected request X-Forwarded-For.
• X-Rate-Limit-Request-Remote-Addr The rejected request RemoteAddr.

If a client continues to make requests despite having no tokens available, the response will be:

• REST: HTTP 429 StatusTooManyRequests for HTTP APIs
• gRPC: 14 Unavailable

Each unsuccessful response will deduct a token from a separate bucket with the same refill rate and capacity as the requests bucket.

Exhausting the supply of tokens in this second bucket will result in the client's IP address being banned for a period of time determined by the data node operators, with 10 minutes as the default.

If banned, the response will be HTTP 403 Forbidden for HTTP APIs.

Read more about rate limiting in the rate limiting README ↗ on GitHub.

Formatting and field conventions

Strings vs numbers format

Often when an API requires a number, it uses the string data type. Numerical fields are passed in string format so that there is no loss of precision, or risk of integer overflow for large numbers.

Decimal precision

The APIs don't provide or accept decimal points in numbers or strings, so the decimal precision must be calculated and the number represented in integers, depending on what decimal precision the number needs.

• For quotes and prices, use the market decimal places to calculate, which can be found by querying for a market's parameters and using decimalPlaces.
• For fees, margin, and liquidity, use the settlement asset decimal places to calculate, which can be found by querying an asset's parameters and using decimals.

Timestamps

Unless otherwise specified, response timestamps are encoded as a Unix timestamp, which is counted from midnight on 1 January, 1970. Requests that require timestamps will also need to be submitted in Unix time. Whether it's a nanosecond, second, or other, is signposted in the tutorial or API reference documentation.

Available frameworks

REST for easy API access

REST provides endpoints for querying for trading data, account information, ledger movements, asset and market information, and much more. While the data provided through REST can come from three different places, the bulk of data can be acquired by querying the trading data API, which is served through data nodes.

REST is easy to get started with, and Vega supports nearly all the functionality provided by gRPC and GraphQL though REST.

Using REST: Read the REST overview for everything you need to know before using the endpoints, like the default rate limits and how to paginate results.

WebSockets for streaming

WebSocket endpoints offer real-time updates to changes in state, allowing subscriptions to events such as per-market trades or changes to a party's position.

gRPC for fast interactions

gRPC provides fast and efficient communication, and supports near real time streaming of updates from Vega.

GraphQL for web apps

GraphQL is an alternative to REST that can be used to craft more complex queries.

Try out queries and learn the structure with the GraphQL playground ↗

Asset bridges

Vega uses ERC-20 assets from Ethereum and Arbitrum, and to facilitate inter-chain interactions between Vega and other chains, those assets are then transferred through a series of smart contract bridges. These bridges let participants use ERC-20 and other assets on the (non-Ethereum) Vega chain.

Moreover, these smart contract bridges operate just like any other smart contract on Ethereum, meaning that users can interact with them directly using a JSON-RPC node provider or a service like Etherscan ↗, or Arbiscan ↗ which provide a user-friendly interface for exploring and interacting with Ethereum and Arbitrum smart contracts, respectively.

Smart contracts

Smart contracts overview: Explore the contracts.

• ERC20 Bridge Logic
  • Contains the functions necessary to deposit, withdraw, list assets, etc. It's controlled by Multisig Control and controls Asset Pool.
• ERC20 Asset Pool
  • Holds deposited assets and remits them to provided addresses based on orders from the assigned Bridge Logic. It is controlled by Bridge Logic and Multisig Control.
• Multisig Control
  • Handles verification of orders signed by a threshold of validators.
• Staking Bridge
  • Allows users to deposit and withdraw governance tokens for staking. The governance tokens are always controlled exclusively by the tokenholder, even when on the Staking Bridge. Stake can be removed at any time by the tokenholder.
• VEGA Token contract
  • ERC20 token smart contract.

For any smart contracts unique to a project using the Vega software, refer to the operator's documentation.

Ethereum addresses

Name	Address	Network
Ethereum ERC20 Bridge	0x7fe27d970bc8Afc3B11Cc8d9737bfB66B1efd799 🔍	Ethereum (Sepolia)
Staking bridge	0xFFb0A0d4806502ceF491aF1141f66669A1Bd0D03 🔍	Ethereum (Sepolia)
Token vesting	0x680fF88252FA7071CAce7398e77872d54D781d0B 🔍	Ethereum (Sepolia)
Vega token	0xdf1B0F223cb8c7aB3Ef8469e529fe81E73089BD9 🔍	Ethereum (Sepolia)
Arbitrum Bridge	0x927067717B0A9bd553fC421Ae63b3377694b4166 🔍	Arbitrum (Sepolia)