Background
In order to query or execute via the Vektor API, you need to refer to existing entities, such as blockchains, venues or asset. For convenience, multiple ways to refer to the same entities are provided. The two main ways are Symbols and IDs:
Symbols
There are currently three types of symbols: blockchain, venue and asset symbols. They use snake_case.
Blockchain symbols follow the pattern name_network e.g. ethereum_mainnet, bnbchain_mainnet, etc. For a full list of supported blockchain symbols, see the /registry/blockchains endpoint.
Examples of venue symbols are curve, uniswap_v2, aave_v2 etc. For a full list of supported venue symbols, check the /registry/venues endpoint.
Examples of asset symbols are eth, weth, usdc, usdt etc. Asset symbols are contextual and are always resolved in the context of the blockchain field. For instance, usdc on ethereum_mainnet refers to a different entity than usdc on bnbchain_mainnet. For a full list of supported asset symbols, check the /registry/assets endpoint.
IDs
Currently five types of entities have IDs:
- Blockchains
- Venues
- Assets
- LP pools
- Lend and Borrow markets.
They are TypeIDs, which are essentially a prefix indicating the entity type, followed by an underscore and a 26-character string. Examples are asset_01jbz9qc0zfc5rnysvk4mf7kft, blockchain_01jbz9nsy8ed8sh5w9b2ybydzc, venue_01jbz9qc18e70895j98ntk3qvh, lp_pool_01jcgaxgmzfd4a6vvqg7c37azr and lend_borrow_market_01jc6vegryejea5gebhxf1073f.
Notice that lend and borrow markets share the same ID, as the objects returned by /lend/markets and /borrow/markets are essentially different views of the same entity.
All endpoints accepting IDs validate the entities match the request's blockchain. Passing an asset ID for an asset on bnbchain_mainnet on a request whose blockchain is ethereum_mainnet will result in a validation error.
For entities such as assets, blockchains or venues, IDs may feel cumbersome and redundant. However, they provide a blockchain-independent way of uniquely identifying and entity. Furthermore, for entities such as LP pools and lend/borrow markets, there are no symbols, only IDs.
Fields accepting both Symbols and IDs
Most fields in most endpoints accept both ways to refer to an entity. If the field is a list, it's allowed to mix both forms in the same list. Typically, the fields:
- asset/assets:accept both asset symbols, asset IDs or EVM addresses (for the contract address). A notable exception is /bridge, which only accepts symbols, as a single symbol is enough to resolve assets in two blockchains.
- venue, venues: accept both venue IDs and symbols.
- blockchain: accepts both blockchain symbols and IDs.