Using Vega's APIs

Using Vega’s APIs

Introduction to APIs at Vega

There are complete REST, gRPC, and GraphQL APIs to suit your integration needs. Whether developing a bot, web app, or custom trading script, the APIs we document below are the same as used by the Vega Console to provide a reference trading user interface.


An example of the Vega API architecture

The diagram above shows an example Vega API architecture, including the relationship between nodes:

  • APIs are typically hosted by non-validator Vega nodes and in the future a smaller set of APIs will be available on validator nodes if configured.
  • Vega Wallets can be hosted locally, or in the cloud, and there’s a helpful REST API built into the reference wallet implementation which can assist API clients with signing and key management.

Which API type is best to integrate with?

Depending on your preference of coding language and streaming requirements, we provide the following recommendations:

1. GRPC

We would recommend gRPC for fast and efficient communication with Vega’s APIs. gRPC supports near real time streaming of updates from Vega. gRPC/Protobuf is the transport of choice for many web3 apps.

2. GRAPHQL

If you’re already familiar with GraphQL or writing a modern web application, we would recommend GraphQL for its flexibility and ability to retrieve data efficiently with Vega’s APIs. Like gRPC, GraphQL supports near real time streaming of updates from Vega. It uses websockets under the hood but follows the specification for streaming as set by GraphQL.

3. REST

REST is the ubiquitous protocol for the web, and one that many still rely on. It’s verbose but pretty easy to get started with and Vega supports nearly all the functionality provided by gRPC and GraphQL on the REST APIs. Sadly, REST does not support streaming.

How do I get an API key for Vega?

We don’t provide API keys. All endpoints are public, in that anyone can call them. However, some endpoints require messages to be cryptographically signed in order to verify that the person sending the message is in control of the associated private key. To do so a user must interact with a Vega Wallet.

Please see the Getting started how-to guide or the section on Signing and Wallets for more information on signing.

What are the Testnet API server addresses?

Load-balanced access to API nodes:

  • REST: https://lb.testnet.vega.xyz/
  • GraphQL: https://lb.testnet.vega.xyz/query
  • gRPC: n06.testnet.vega.xyz:3002 (gRPC is available on all API nodes below on port 3002)

Geographical API nodes (non-validator):

  • https://n06.testnet.vega.xyz (Europe, Netherlands)
  • https://n07.testnet.vega.xyz (Europe, Finland)
  • https://n08.testnet.vega.xyz (Asia, Hong Kong)
  • https://n09.testnet.vega.xyz (North America, USA, Virginia)

Hosted Wallet API:

  • REST: https://wallet.testnet.vega.xyz

Please see the section on Introducing Testnet for more information on the testnet including total number of nodes, limitations and upcoming features.

How do decimal places work in API calls?

The API deals entirely in whole numbers, so assets are labelled with a decimal place indicator to help API users convert prices to their correct value.

Currency Balance decimalPlaces Real Balance
GBP 123 0 123.0000
GBP 123 2 1.2300
GBP 123 4 0.0123
ETH 1234500000000000000 18 1.2345

How do I use websockets with Vega APIs?

There are currently no stand-alone websocket based streaming APIs, however we recommend looking at the GraphQL subscriptions feature which provides streaming updates and under the hood uses the websocket protocol for data transmission. GraphQL is very flexible and powerful for modern client integrations.

How do I contribute to the project?

Find a list of available bounties on the Vega bounties GitHub. If you have ideas for other bounties, post them in the bounty section of the community forum.

Otherwise, reach out to us on the community forum or Discord chat to enquire further about how to get involved.

If you have found an issue or would like to suggest an improvement with the public code samples, please raise an issue on the appropriate GitHub repository.

Do you have API reference docs available?

Yes, there are auto-generated API docs for the following:

Do you have any code samples or guides?

Yes, please visit the API How-to Guides section to start your journey.
You can also run code samples directly against the Vega testnet using Gitpod.