ZaaS GRPC API
GRPC API doc for ZaaS API
Last updated
Was this helpful?
GRPC API doc for ZaaS API
Last updated
Was this helpful?
Please refer to the following server configuration and proto file for the grpc API. You can use https://buf.build/ along with its plugin https://buf.build/grpc-ecosystem/gateway to generate a grpc client. Refer to https://github.com/grpc-ecosystem/grpc-gateway/tree/main/examples/internal/clients for some example code.
Server address
zap-api.kyberswap.com:443
Header X-Chain-ID
42161 for arbitrum
43114 for avalanche
8453 for base
56 for bsc
1 for ethereum
59144 for linea
10 for optimism
137 for polygon
1101 for polygon-zkevm
Refer to the supported chains page for the latest list
Header X-Client-ID
Some value to identify your client.
Please contact bd@kyber.network to whitelist your client id with more rate limit quota
Download zap.proto:
syntax = "proto3";
package zap.v1;
import "buf/validate/validate.proto";
import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
// Dex is the type of dex to zap into/out of. It uses different enum values from the zap contract.
enum Dex {
// Unspecified value.
DEX_UNSPECIFIED = 0;
// For UniSwap V3.
DEX_UNISWAPV3 = 2;
// For PancakeSwap V3.
DEX_PANCAKESWAPV3 = 3;
// For Uniswap V2.
DEX_UNISWAPV2 = 4;
// For SushiSwap V2.
DEX_SUSHISWAPV2 = 5;
// For Curve
DEX_CURVE = 6;
}
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "Zap Service"
description: "Zap Service for quickly zapping pool liquidity in a single transaction"
version: "1.2.0"
contact: {
url: "https://discord.gg/kyberswap"
email: "bd@kyber.network"
}
}
host: "pre-zap-api.kyberengineering.io"
base_path: "/{chain}"
schemes: HTTPS
responses: {
key: "400"
value: {
description: "Invalid Argument"
schema: {
json_schema: {ref: "#/definitions/rpcStatus"}
}
examples: {
key: "application/json"
value:
'{"code":3, "message":"validation error:\\\\\\\\n'
' - pool: missing tokens [Pool.tokens]\\\\\\\\n'
' - pool.id: value does not match regex pattern `^0x[0-9A-Za-z]{40}$` [string.pattern]\\\\\\\\n'
' - position: value is required [required]\\\\\\\\n'
' - token_in[0]: value does not match regex pattern `^0x[0-9A-Za-z]{40}(,0x[0-9A-Za-z]{40})*$` [string.pattern]\\\\\\\\n'
' - amount_in[0]: value does not match regex pattern `^\\\\\\\\d+(,\\\\\\\\d+)*$` [string.pattern]\\\\\\\\n'
' - fee_address: value does not match regex pattern `^0x[0-9A-Za-z]{40}$` [string.pattern]"}'
}
}
}
responses: {
key: "404"
value: {
description: "Not Found"
schema: {
json_schema: {ref: "#/definitions/rpcStatus"}
}
examples: {
key: "application/json"
value: '{"code":5, "message":"failed to get zap routes: cannot swap tokens [0xE2035f04040A135c4dA2f96AcA742143c57c79F9]"}'
}
}
}
};
// Service allows getting and building zap routes.
service Service {
// Get the best zap-in route.
rpc GetInRoute(GetInRouteRequest) returns (GetInRouteResponse) {
option (google.api.http) = {get: "/api/v1/in/route"};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
parameters: {
headers: {
name: "X-Client-Id"
description: "Client Id"
type: STRING
}
headers: {
name: "X-Request-Id"
description: "Request Id"
type: STRING
}
}
};
}
// Decode zap-in route for debugging purposes.
rpc DecodeInRoute(DecodeInRouteRequest) returns (DecodeInRouteResponse) {
option (google.api.http) = {
post: "/api/v1/in/route/decode"
body: "*"
};
}
// Build encoded data for the specified zap-in route.
rpc BuildInRoute(BuildInRouteRequest) returns (BuildInRouteResponse) {
option (google.api.http) = {
post: "/api/v1/in/route/build"
body: "*"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
parameters: {
headers: {
name: "X-Client-Id"
description: "Client Id"
type: STRING
}
headers: {
name: "X-Request-Id"
description: "Request Id"
type: STRING
}
}
};
}
// Get the best zap-migrate route.
rpc GetMigrateRoute(GetMigrateRouteRequest) returns (GetMigrateRouteResponse) {
option (google.api.http) = {get: "/api/v1/migrate/route"};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
parameters: {
headers: {
name: "X-Client-Id"
description: "Client Id"
type: STRING
}
headers: {
name: "X-Request-Id"
description: "Request Id"
type: STRING
}
}
responses: {
key: '200'
value: {
description: "OK"
examples: {
key: 'application/json'
value: '{"code":0,"data":{}}'
}
}
}
};
}
// Decode zap-migrate route for debugging purposes.
rpc DecodeMigrateRoute(DecodeMigrateRouteRequest) returns (DecodeMigrateRouteResponse) {
option (google.api.http) = {
post: "/api/v1/migrate/route/decode"
body: "*"
};
}
// Build encoded data for the specified zap-migrate route.
rpc BuildMigrateRoute(BuildMigrateRouteRequest) returns (BuildMigrateRouteResponse) {
option (google.api.http) = {
post: "/api/v1/migrate/route/build"
body: "*"
};
}
}
// Get the best zap-in route.
message GetInRouteRequest {
// which dex to use zap with
Dex dex = 1;
// the pool to zap into
Pool pool = 2 [(buf.validate.field).required = true];
// position details
Position position = 3 [(buf.validate.field).required = true];
// which token(s) to use as zap source. also accepts comma separated addresses
repeated string tokens_in = 4 [(buf.validate.field).repeated.items.string.pattern = "^0x[0-9A-Za-z]{40}(,0x[0-9A-Za-z]{40})*$"];
// amount(s) to zap including fee, corresponding to tokenIn. also accepts comma separated amounts.
repeated string amounts_in = 5 [(buf.validate.field).repeated.items.string.pattern = "^\\d+(,\\d+)*$"];
// which token(s) to use as zap source. also accepts comma separated addresses.
// deprecated: use tokens_in. if both fields are specified, they are combined
repeated string token_in = 14 [(buf.validate.field).repeated.items.string.pattern = "^0x[0-9A-Za-z]{40}(,0x[0-9A-Za-z]{40})*$"];
// amount(s) to zap including fee, corresponding to tokenIn. also accepts comma separated amounts.
// deprecated: use amounts_in. if both fields are specified, they are combined
repeated string amount_in = 15 [(buf.validate.field).repeated.items.string.pattern = "^\\d+(,\\d+)*$"];
option (buf.validate.message).cel = {
id: "GetInRouteRequest.tokens_in"
message: "missing tokens_in"
expression: "has(this.token_in) || has(this.tokens_in)"
};
option (buf.validate.message).cel = {
id: "GetInRouteRequest.amounts_in"
message: "missing amounts_in"
expression: "has(this.amount_in) || has(this.amounts_in)"
};
// aggregator options
AggregatorOptions aggregator_options = 6;
// the address of the fee recipient.
string fee_address = 7 [(buf.validate.field) = {
string: {pattern: "^0x[0-9A-Za-z]{40}$"}
ignore: IGNORE_IF_UNPOPULATED
}];
// fee percentage in per cent mille (0.001% or 1 in 100,000). Ignored if feeAddress is empty.
// From 0 to 100,000 inclusively. Example: 1 for 0.001%.
uint32 fee_pcm = 8 [(buf.validate.field).uint32 = {
gte: 0
lte: 100000
}];
// maximum slippage tolerance in basis points (0.01%), used for aggregator (exceeding which the transaction will
// revert) and pool swap during zap (for additional zapping and for refund).
// From 0 to 10,000 inclusively. Example: 1 for 0.01%.
uint32 slippage = 9 [(buf.validate.field).uint32 = {
gte: 0
lte: 10000
}];
}
// options for getting aggregator routes
message AggregatorOptions {
// whether to disable swapping with the aggregator
bool disable = 1;
// comma-separated list of sources to use for aggregator
string included_sources = 2;
// comma-separated list of sources to exclude for aggregator
string excluded_sources = 3;
}
// Pool describes the pool to zap into.
message Pool {
// id of the pool to zap into.
string id = 1 [(buf.validate.field).string.pattern = "^0x[0-9A-Za-z]{40}$"];
}
// Position describes either an existing position or a new one.
message Position {
option (buf.validate.message).cel = {
id: "position.ticks_check"
message: "tick_lower must be less than tick_upper"
expression: "!(has(this.tick_lower) || has(this.tick_upper)) || this.tick_lower < this.tick_upper"
};
// id of the position to add liquidity to; omit to create a new uniswapV3 position. for uniswapV2 this is user address
optional string id = 1;
// min tick of the position, required if creating a new uniswapV3 position.
optional sint32 tick_lower = 2;
// max tick of the position, required if creating a new uniswapV3 position.
optional sint32 tick_upper = 3;
}
// Returns the best route to zap-in to the specified pool position.
message GetInRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
PoolDetails pool_details = 1;
PositionDetails position_details = 2;
// zap details
ZapDetails zap_details = 3;
// the zap route to pass to build API to get call-data
bytes route = 4;
// the router address to check approval amount
string router_address = 5;
// rough estimate of gas required for the transaction
string gas = 6;
// USD value of estimated gas required
string gas_usd = 7;
}
}
// details of the pool
message PoolDetails {
string category = 1;
oneof pool {
UniswapV3 uniswap_v3 = 8;
UniswapV2 uniswap_v2 = 9;
}
// details of the uniswapV3 pool
message UniswapV3 {
// pool tick before zap
optional sint32 tick = 1;
// pool tick after zap
optional sint32 new_tick = 2;
// pool sqrt price (times 2^96) before zap
optional string sqrt_p = 3;
// pool sqrt price (times 2^96) after zap
optional string new_sqrt_p = 4;
}
// details of the uniswapV2 pool
message UniswapV2 {
// reserve0 before zap
optional string reserve0 = 1;
// reserve0 after zap
optional string new_reserve0 = 2;
// reserve1 before zap
optional string reserve1 = 3;
// reserve1 after zap
optional string new_reserve1 = 4;
}
}
// details of the new position state
message PositionDetails {
// how much position liquidity to be removed
string removed_liquidity = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field).pattern = "\\d+"];
// total USD value of the position to be removed
string removed_amount_usd = 2;
// how much position liquidity to be added
string added_liquidity = 3 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field).pattern = "\\d+"];
// total USD value of the position to be added
string added_amount_usd = 4;
}
// details of the zap
message ZapDetails {
// USD value of the source zap token amount
string initial_amount_usd = 1;
// list of zap actions
repeated Action actions = 2;
// one of the zap actions, specified by the type field
message Action {
ActionType type = 1;
oneof action {
FeeAction protocol_fee = 2;
FeeAction partner_fee = 3;
SwapAction aggregator_swap = 4;
SwapAction pool_swap = 5;
LiquidityAction add_liquidity = 6;
LiquidityAction remove_liquidity = 7;
RefundAction refund = 8;
}
}
// type of the zap action
enum ActionType {
// Unspecified action
ACTION_TYPE_UNSPECIFIED = 0;
// protocol fee
ACTION_TYPE_PROTOCOL_FEE = 1;
// partner fee
ACTION_TYPE_PARTNER_FEE = 2;
// aggregator swap
ACTION_TYPE_AGGREGATOR_SWAP = 3;
// pool swap
ACTION_TYPE_POOL_SWAP = 4;
// add liquidity
ACTION_TYPE_ADD_LIQUIDITY = 5;
// remove liquidity
ACTION_TYPE_REMOVE_LIQUIDITY = 6;
// refund
ACTION_TYPE_REFUND = 7;
}
// fee collection
message FeeAction {
// fee per cent mille (0.001%) of the source zap amount
uint32 pcm = 1;
// token amounts
repeated TokenAmount tokens = 2;
}
// token swap, either with aggregator or with pool
message SwapAction {
repeated Swap swaps = 1;
// a single swap
message Swap {
// swapped token amount
TokenAmount token_in = 1;
// returned token amount
TokenAmount token_out = 2;
}
}
// added or removed liquidity
message LiquidityAction {
// added or removed token amounts
repeated TokenAmount tokens = 1;
// collected fees
repeated TokenAmount fees = 2;
// added or removed token 0 amount. deprecated: use tokens
TokenAmount token0 = 3;
// added or removed token 1 amount. deprecated: use tokens
TokenAmount token1 = 4;
}
// refund left-over tokens to user
message RefundAction {
// refunded token amounts
repeated TokenAmount tokens = 1 [(buf.validate.field).repeated.items.required = true];
}
// token address and amount in wei and in usd
message TokenAmount {
// token address
string address = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field).pattern = "^0x[0-9A-Za-z]{40}$"];
// wei amount of the token
string amount = 2;
// USD value of the token
string amount_usd = 3;
}
// USD value of the final amount including the added position and the left-over amount
string final_amount_usd = 3;
// price impact after zapping of final amount against initial amount
optional float price_impact = 4;
}
// Decode zap-in route for debugging purposes.
message DecodeInRouteRequest {
// the route as returned from get-route endpoint.
bytes route = 1;
}
// Returns the zap-in route details.
message DecodeInRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
// JSON encode of the zap in route.
string json = 1;
}
}
// Build encoded data for zap-in transaction from the specified route.
message BuildInRouteRequest {
// the wallet sending the transaction, and thus, the tokens.
string sender = 1 [(buf.validate.field).string.pattern = "^0x[0-9A-Za-z]{40}$"];
// the wallet receiving the new position. default to sender if empty.
string recipient = 2 [(buf.validate.field) = {
string: {pattern: "^0x[0-9A-Za-z]{40}$"}
ignore: IGNORE_IF_UNPOPULATED
}];
// the route as returned from get-route endpoint.
bytes route = 3;
// deadline for the swap transaction to execute.
fixed32 deadline = 4 [(buf.validate.field).cel = {
id: "deadline.gte_now"
message: "deadline must be in the future"
expression: "this == 0u || this > int(now)"
}];
// the source of the zap-in transaction.
string source = 5;
// map of each token address to its ERC20 permit using EIP-2612 to skip a separate approval step.
map<string, string> permits = 6 [
(buf.validate.field).map.keys.string.pattern = "^0x[0-9A-Za-z]{40}$",
(buf.validate.field).map.values.string.pattern = "^0x[0-9A-Za-z]{448}$"
];
}
// Returns the zap-in transaction details.
message BuildInRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
// zap router address to send the zap-in transaction to
string router_address = 1;
// call data for the zap-in transaction
string call_data = 2;
// native token value to transfer with the zap-in transaction in case of zapping with native tokens
string value = 3;
}
}
// Get the best zap-migrate route.
message GetMigrateRouteRequest {
// which dex to zap migrate out from
Dex dex_from = 10;
// which dex to zap migrate in to
Dex dex_to = 1;
// the pool to zap into
Pool pool_from = 11 [(buf.validate.field).required = true];
// the pool to zap into
Pool pool_to = 2 [(buf.validate.field).required = true];
// old position details
Position position_from = 12 [
(buf.validate.field).required = true,
(buf.validate.field).cel = {
id: "position_from.has_id"
message: "position_from must provide an existing nft id"
expression: "has(this.id)"
}
];
// new position details
Position position_to = 3 [(buf.validate.field).required = true];
// liquidity amount to withdraw, or empty or 0 to withdraw all
string liquidity_out = 4 [(buf.validate.field).string.pattern = "^\\d*$"];
// aggregator options
AggregatorOptions aggregator_options = 6;
// options for getting aggregator routes
// the address of the fee recipient.
string fee_address = 7 [(buf.validate.field) = {
string: {pattern: "^0x[0-9A-Za-z]{40}$"}
ignore: IGNORE_IF_UNPOPULATED
}];
// fee percentage in per cent mille (0.001% or 1 in 100,000). Ignored if feeAddress is empty.
// From 0 to 100,000 inclusively. Example: 1 for 0.001%.
uint32 fee_pcm = 8 [(buf.validate.field).uint32 = {
gte: 0
lte: 100000
}];
// maximum slippage tolerance in basis points (0.01%), used for aggregator (exceeding which the transaction will
// revert) and pool swap during zap (for additional zapping and for refund).
// From 0 to 10,000 inclusively. Example: 1 for 0.01%.
uint32 slippage = 9 [(buf.validate.field).uint32 = {
gte: 0
lte: 10000
}];
}
// Returns the best route to zap-migrate from an existing position to the specified pool position.
message GetMigrateRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
PoolDetails pool_details = 1;
PositionDetails position_details = 2;
// zap details
ZapDetails zap_details = 3;
// the zap route to pass to build API to get call-data
bytes route = 4;
// the router address to check approval amount
string router_address = 5;
// rough estimate of gas required for the transaction
string gas = 6;
// USD value of estimated gas required
string gas_usd = 7;
}
}
// Decode zap-migrate route for debugging purposes.
message DecodeMigrateRouteRequest {
// the route as returned from get-route endpoint.
bytes route = 1;
}
// Returns the zap-migrate route details.
message DecodeMigrateRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
// JSON encode of the zap in route.
string json = 1;
}
}
// Build encoded data for zap-migrate transaction from the specified route.
message BuildMigrateRouteRequest {
// the wallet sending the transaction, and thus, the tokens.
string sender = 1 [(buf.validate.field).string.pattern = "^0x[0-9A-Za-z]{40}$"];
// the wallet receiving the new position. default to sender if empty.
string recipient = 2 [(buf.validate.field) = {
string: {pattern: "^0x[0-9A-Za-z]{40}$"}
ignore: IGNORE_IF_UNPOPULATED
}];
// the route as returned from get-route endpoint.
bytes route = 3;
// deadline for the swap transaction to execute.
fixed32 deadline = 4 [(buf.validate.field).cel = {
id: "deadline.gte_now"
message: "deadline must be in the future"
expression: "this == 0u || this > int(now)"
}];
// the source of the zap-migrate transaction.
string source = 5;
// whether to throw away the position NFT or keep it.
bool burn_nft = 6;
}
// Returns the zap-migrate transaction details.
message BuildMigrateRouteResponse {
// grpc error code
int32 code = 1;
// grpc error message
string message = 2;
// response data
Data data = 3;
// request trace id
string request_id = 4;
// Encompasses returned data.
message Data {
// zap router address to send the zap-migrate transaction to
string router_address = 1;
// call data for the zap-migrate transaction
string call_data = 2;
// native token value to transfer with the zap-migrate transaction in case of zapping with native tokens
string value = 3;
}
}