Vega API

Version: 0.41.0

This repository contains everything you need for interacting with the Vega APIs.

There are currently 3 APIs:

gRPC
GraphQL
REST

gRPC

See https://grpc.io/ for general information on gRPC.

Vega provides a rich gRPC API. For a complete list of endpoints, see proto/api/trading.proto:

Use TradingService for:
- Prepare* endpoints are there for convenience, and will be removed in the near future
- SubmitTransaction receives and executes a signed transaction. For transaction signing, see go-wallet.
Use TradingDataService for public information on:
- assets, e.g. Ethereum ERC20 tokens
- balances for accounts: general, margin
- market data and metadata
- information on orders and trades
- Governance data: proposals, votes
- event stream subscriptions for the above

Before writing your own API client (either manually or using auto-generation), check if a pre-created on is already available. See Auto-generated gRPC clients below.

GraphQL

See https://graphql.org/ for general information on GraphQL.

Vega provides a fully-featured GraphQL API. For the complete schema, see graphql/schema.graphql.

The GraphQL Playground is enabled for convenience on Testnet non-validator nodes: https://lb.testnet.vega.xyz/playground.

It is possible to use nested queries that return only the desired information.

REST

Vega provides a limited REST API. Streaming of events is not supported.

For an OpenAPI json file that describes all available endpoints, see rest/api/trading.swagger.json. The mapping between gRPC endpoints and their REST equivalent is found in rest/grpc-rest-bindings.yml.

Auto-generated gRPC clients

Vega uses buf to auto-generate API clients in various programming languages. The list of currently supported clients is found in buf.gen.yaml, and the full build process is in the Makefile.

The per-language API clients are found in grpc/clients/.

Pull requests for additional languages are gratefully received.

Examples

Some example/demonstration programs are maintained in this repository. They are intended to be stand-alone programs that can be run by people copying and editing the source code.

API	Directory
gRPC	`grpc/examples/`
GraphQL	`graphql/examples/`
REST	`rest/examples/`

Information for maintainers

Update process - gRPC

Install buf: https://docs.buf.build/installation/

# Copy proto files from Core
cd .../api # repo root dir
VEGACORE=/path/to/go/src/vega make preproto

# Generate gRPC API clients, gRPC documentation, REST OpenAPI json.
make proto

# Run tests
GRPC_NODE=veganode.example.com:1234 WALLETSERVER=https://vegawallet.example.com make test

Java gRPC generation

Run the update for gRPC in general and this will generate all the Java source files.

Install maven

Linux: sudo apt install maven

Run ./make-jar.sh in the grpc/clients/java directory.

Update process - GraphQL

# Copy schema.graphql from Core
cd .../api/graphql
VEGACORE=/path/to/go/src/vega make pregraphql

# Generate GraphQL documentation
make graphql

Release process

./setversion.sh 1.2.3  # no "v" prefix

Licence

Distributed under the MIT License. See LICENSE for more information.

vegaprotocol/api