Introduction
This documentation describes how to interact with the Spin DEX Perp. The first section describes the list of on-chain smart contract methods for all write operations (deposit, withdraw, placing and cancelling orders) and some read operations (get base currency and markets info, get balance, get orderbook, get orders). The second section describes getting data via the Gateway API. Gateway API is an off-chain service that collects and aggregates the results of execution of operations on a smart contract and provides convenient endpoints for receiving them. All API methods are called through JSON-RPC 2.0 protocol via websocket.
Changelog
2022-11-08
Public release Perp API
Decimals
Contract Decimals
> near view v2_0_2.perp.spin-fi.testnet get_order '{"market_id": 1, "order_id": "1", "account_id": "user.testnet"}'
{
"id": "1",
"acc": "user.testnet",
"price": "4500000000000000000000000", # <-- decimals = 24
"average_price": "4500000000000000000000000", # <-- decimals = 24
"quantity": "50000000000000000000000000", # <-- decimals = 24
"remaining": "6000000000000000000000000", # <-- decimals = 24
"updated_at": "1649164215000000000",
"created_at": "1648838833603256735",
"o_type": "Bid",
"client_order_id": null,
"time_in_force": 'GTC',
"post_only": false
}
Most numerical values have 24 decimals or decimals will be written explicitly.
Gateway API Decimals
All numerical values have 24 decimals or decimals will be written explicitly.
Faucet Testnet Contract API
Faucet Testnet Contract is used to get test USDC tokens. Contract is deployed to NEAR blockchain testnet account airdrop.spin-fi.testnet and can be viewed here.
Call next contract methods to get 1000 USDC every 24 hours.
near view usdc.spin-fi.testnet ft_balance_of '{"account_id": "'<YOUR_ACCOUNT_ID>'"}'
near view usdc.spin-fi.testnet storage_balance_bounds
near call usdc.spin-fi.testnet storage_deposit '' --accountId <YOUR_ACCOUNT_ID> --depositYocto <min> # where <min> - value from `storage_balance_bounds` command result
near call airdrop.spin-fi.testnet airdrop '{"token": "'usdc.spin-fi.testnet'"}' --gas=300000000000000 --accountId <YOUR_ACCOUNT_ID> --depositYocto 2
near view airdrop.spin-fi.testnet cool_down '{"account": "'<YOUR_ACCOUNT_ID>'", "token": "'usdc.spin-fi.testnet'"}'
near view usdc.spin-fi.testnet ft_balance_of '{"account_id": "'<YOUR_ACCOUNT_ID>'"}'
Perp Contract API
Use near call to call contract methods.
Testnet
Contract is deployed to NEAR blockchain testnet account v2_0_2.perp.spin-fi.testnet and can be viewed here.
Mainnet
Contract is deployed to NEAR blockchain mainnet account v2_0_2.perp.spin-fi.near and can be viewed here.
Perp Contract API
Markets
get_base_currency
near view v2_0_2.perp.spin-fi.testnet get_base_currency
Response:
{
"address": "usdc.spin-fi.testnet",
"decimals": 2,
"symbol": "USDC",
"max_deposit": "500000000000000000000000000"
}
Returns base (or collateral) currency supported by the contract.
Response
| Name | Type | Enum | Description |
|---|---|---|---|
| address | string | Currency ft contract address | |
| decimals | number | Currency decimals | |
| symbol | string | Currency symbol | |
| max_deposit | string | Maximum amount of currency for deposit |
get_market
near view v2_0_2.perp.spin-fi.testnet get_market \
'{
"market_id": 1
}'
Response:
{
"id": 1,
"symbol": "NEAR-PERP",
"leverage": "10000000000000000000000000",
"fees": {
"maker_fee": "400",
"taker_fee": "800",
"decimals": 6,
"is_rebate": true
},
"availability": {
"allow_place": true,
"allow_cancel": true
},
"limits": {
"tick_size": "1000000000000000000000",
"step_size": "10000000000000000000000",
"min_base_quantity": "100000000000000000000000",
"max_base_quantity": "10000000000000000000000000000",
"min_quote_quantity": "100000000000000000000000",
"max_quote_quantity": "50000000000000000000000000000",
"max_bid_count": 20,
"max_ask_count": 20,
"max_match_count": 24
}
}
Returns market info by ID supported by the contract.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
Response
| Name | Type | Description |
|---|---|---|
| id | number | Market ID |
| symbol | string | Market symbol |
| leverage | string | Max leverage |
| fees | object | |
| › maker_fee | string | Maker fee percent. E.g. maker_fee = 5000 and decimals = 6 means 0.005 (or 0.5%) |
| › taker_fee | string | Taker fee percent. E.g. taker_fee = 10000 and decimals == 6 means 0.01 (or 1%) |
| › decimals | number | Fixed decimals for fee values |
| › is_rebate | string | True means the rebate exists for makers |
| availability | object | |
| › allow_place | bool | Enable or disable order placing |
| › allow_cancel | bool | Enable or disable order cancelling |
| limits | object | |
| › tick_size | string | Minimum precision of the order price. |
| › step_size | string | Minimum precision of the order quantity. |
| › min_base_quantity | string | Minimum base asset quantity for the order |
| › max_base_quantity | string | Maximum base asset quantity for the order |
| › min_quote_quantity | string | Minimum quote asset quantity for the order |
| › max_quote_quantity | string | Maximum quote asset quantity for the order |
| › max_bid_count | number | Limits on the maximum number of bids per user |
| › max_ask_count | number | Limits on the maximum number of asks per user |
| › max_match_count | number | Limits on the maximum number of match within one transaction |
get_markets
near view v2_0_2.perp.spin-fi.testnet get_markets
Response:
[
{
"id": 1,
"symbol": "NEAR-PERP",
"leverage": "10000000000000000000000000",
"fees": {
"maker_fee": "400",
"taker_fee": "800",
"decimals": 6,
"is_rebate": true
},
"availability": {
"allow_place": true,
"allow_cancel": true
},
"limits": {
"tick_size": "1000000000000000000000",
"step_size": "10000000000000000000000",
"min_base_quantity": "100000000000000000000000",
"max_base_quantity": "10000000000000000000000000000",
"min_quote_quantity": "100000000000000000000000",
"max_quote_quantity": "50000000000000000000000000000",
"max_bid_count": 20,
"max_ask_count": 20,
"max_match_count": 24
}
}
]
Returns all markets info supported by the contract.
Response
| Type | Description |
|---|---|
| array of objects | Array of markets (See get_market) |
get_orderbook
near view v2_0_2.perp.spin-fi.testnet get_orderbook \
'{
"market_id": 1,
"limit": 2
}'
Response:
{
"ask_orders": [
{
"price": "2666000000000000000000000",
"quantity": "118765730000000000000000000000"
},
{
"price": "2667000000000000000000000",
"quantity": "62486430000000000000000000000"
}
],
"bid_orders": [
{
"price": "2663000000000000000000000",
"quantity": "118887570000000000000000000000"
},
{
"price": "2662000000000000000000000",
"quantity": "62595900000000000000000000000"
}
]
}
Returns the order book information for a given market ID.
Request
| Parameter | Required | Type | Enum | Description |
|---|---|---|---|---|
| market_id | true | number | ||
| order_type | false | string | Bid, Ask |
Type of orders to select (case-sensitive). If no value both ask and bids are returned |
| limit | false | number | Number of records. Default 15 |
Response
| Name | Type | Description |
|---|---|---|
| ask_orders | array of objects | List of ask orders grouped by price |
| › price | string | Level price |
| › quantity | string | Total quantity at this level price |
| bid_orders | array of objects | See "ask_orders" |
get_funding_info
near view v2_0_2.perp.spin-fi.testnet get_funding_info \
'{
"market_id": 1,
"from": 457563,
"to": 457570
}'
Response:
{
"epoch_index": 463315,
"current_index_price": "2656000000000000000000000",
"prices": {
"27798900": {
"index_price": "2669000000000000000000000",
"mid_price": "2649500000000000000000000"
},
"27798901": {
"index_price": "2667000000000000000000000",
"mid_price": "2659500000000000000000000"
}
},
"rates": {
"463314": {
"funding_rate": "-1119926395513278238573",
"avg_index_price": "2702516666666666666666666"
},
"463315": {
"funding_rate": "-3215879054177387294493",
"avg_index_price": "2595000000000000000000000"
}
},
"current_rate": {
"funding_rate": "-2623935421922916222863",
"avg_index_price": "2667916666666666666666666"
}
}
Returns the funding information for a given market ID for specified period.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
| from | true | number, null | Start epoch index for rates. Optional |
| to | true | number, null | End epoch index for rates. Optional |
Response
| Name | Type | Description |
|---|---|---|
| epoch_index | number | Current epoch index (timestamp == epoch_index * 3600) |
| current_index_price | string | The latest index price from oracle |
| prices | object | Hashmap minute_index -> (index_price, mid_price) |
| › minute_index | string | Minute tick (minute index): timestamp == tick * 60 |
| › › index_price | string | Index price for that minute |
| › › mid_price | string | Middle price ((best_ask + best_bid) / 2) for that minute |
| › ... | ||
| rates | object | Hashmap epoch_index -> (funding_rate, avg_index_price) |
| › epoch_index | string | Epoch index (timestamp == epoch_index * 3600) |
| › › funding_rate | string | Funding rate for that funding epoch |
| › › avg_index_price | string | Average index price for that funding epoch |
| › ... | ||
| current_rate | object | |
| › funding_rate | string | Uncompleted funding rate for the current epoch calculated for already known values. |
| › avg_index_price | string | Uncompleted average index price for the current epoch calculated for already known values. |
get_market_prices
near view v2_0_2.perp.spin-fi.testnet get_market_prices
Response:
{
"1": {
"index_price": "2613000000000000000000000",
"mark_price": "2613000000000000000000000"
}
}
Returns the price information (index_price and mark_price) for all markets.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
Response
| Name | Type | Description |
|---|---|---|
| market_id | object | Market ID |
| › index_price | string | Current index price |
| › mark_price | string | Current mark price |
| ... |
Balances
get_balance
near view v2_0_2.perp.spin-fi.testnet get_balance \
'{
"account_id": "user.testnet"
}'
Response:
"10000"
Returns base currency (or collateral currency) balance. Collateral currency address for testnet is usdc.spin-fi.testnet and for mainnet is a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.factory.bridge.near and can be retriving with this method.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | true | string | User account whose balance we are requesting |
Response
| Name | Type | Description |
|---|---|---|
| collateral_currency_balance | string | Balance of collateral currency |
Deposit Collateral
near call usdc.spin-fi.testnet ft_transfer_call \
'{
"receiver_id": "v2_0_2.perp.spin-fi.testnet",
"amount": "100000",
"msg": ""
}' \
--accountId <YOUR_ACCOUNT_ID> \
--depositYocto 1 \
--gas=300000000000000
To deposit collateral token to your perp account you need to call ft_transfer_call of the token contract and send v2_0_2.perp.spin-fi.testnet as a receiver. You also need to pay for the transfer and attach 1 yoctoⓃ.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| receiver_id | true | string | Token recipient (the perp contract v2_0_2.perp.spin-fi.testnet) |
| amount | true | string | Transfer amount (given the decimals of the token) |
| msg | true | string | Should be empty |
Withdraw Collateral
near call v2_0_2.perp.spin-fi.testnet withdraw \
'{
"token": "usdc.spin-fi.testnet",
"amount": "1000"
}' \
--accountId <YOUR_ACCOUNT_ID> \
--gas=50000000000000
--depositYocto 1
FT account registration:
near view usdc.spin-fi.testnet storage_balance_bounds
near call usdc.spin-fi.testnet storage_deposit '' --accountId <YOUR_ACCOUNT_ID> --depositYocto <min> # where <min> - value from `storage_balance_bounds` command result
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| token | true | string | Could be collateral currency address (i.e. usdc.spin-fi.testnet) |
| amount | true | string | Withdrawal amount (given the decimals of the token) |
50000000000000 gas must be applied to handle possible errors
Orders
get_order
near view v2_0_2.perp.spin-fi.testnet get_order \
'{
"market_id": 1,
"order_id": "1",
"account_id": "user.testnet"
}'
Response:
{
"id": "27598",
"acc": "user.testnet",
"price": "2591000000000000000000000",
"average_price": "0",
"quantity": "1000000000000000000000000",
"remaining": "1000000000000000000000000",
"updated_at": "0",
"created_at": "1667940871126558376",
"o_type": "Bid",
"client_order_id": null,
"time_in_force": "GTC",
"post_only": false
}
Returns the current information about order by market ID, order ID and account ID.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
| order_id | true | string | Order ID |
| account_id | true | string | Account ID |
Response
| Name | Type | Enum | Description |
|---|---|---|---|
| id | string | Order ID | |
| acc | string | Account ID of the order owner | |
| price | string | Price of a order | |
| average_price | string | Average price of a order | |
| quantity | string | Quantity of items in order | |
| remaining | string | Remaining quantity | |
| updated_at | string | Timestamp of the last modification of the order | |
| created_at | string | Timestamp of the order creation | |
| o_type | string | Ask, Bid |
Order type |
| client_order_id | number, null | Optional non-unique client order ID | |
| time_in_force | string | GTC, GTD, FOK |
Time-in-force: good-til-cancel (GTC), good-til-day (GTD) or fill-or-kill (FOK) |
| post_only | boolean | Post-only parameter: execution will be only as maker |
get_orders
near view v2_0_2.perp.spin-fi.testnet get_orders \
'{
"market_id": 1,
"account_id": "medvi.testnet"
}'
Response:
[
{
"id": "27598",
"acc": "user.testnet",
"price": "2591000000000000000000000",
"average_price": "0",
"quantity": "1000000000000000000000000",
"remaining": "1000000000000000000000000",
"updated_at": "0",
"created_at": "1667940871126558376",
"o_type": "Bid",
"client_order_id": null,
"time_in_force": "GTC",
"post_only": false
}
]
Returns a list of orders belonging to a given account on a specified market;
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
| account_id | true | string | Account ID |
Response
| Type | Description |
|---|---|
| array of objects | Array of orders (See get_order) |
place_ask
near call v2_0_2.perp.spin-fi.testnet place_ask \
'{
"market_id": 1,
"price": "1000000000000000000000000",
"quantity": "2000000000000000000000000",
"market_order": false,
"client_order_id": 1,
"time_in_force": "GTC",
"post_only": false,
"deadline": "1645253261237547000"
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
"1"
Request
Place a sell order.
| Parameter | Required | Type | Enum | Description |
|---|---|---|---|---|
| market_id | true | number | Market ID | |
| price | true | string | Order price. If market_order is True, the price is required anyway and is used as a slippage |
|
| quantity | true | string | Order quantity | |
| market_order | true | boolean | A sign that the order is market | |
| client_order_id | false | number | Non-unique client order ID | |
| time_in_force | false | string | GTC, GTD, FOK |
Time-in-force: good-til-cancel (GTC), good-til-day (GTD) or fill-or-kill (FOK) |
| post_only | false | bool | Post-only parameter: order will be executed only as maker | |
| deadline | true | string | Transaction execution deadline. Time in nanoseconds. |
Response
| Type | Description |
|---|---|
| string | ID of placed order |
place_bid
near call v2_0_2.perp.spin-fi.testnet place_bid \
'{
"market_id": 1,
"price": "1000000000000000000000000",
"quantity": "2000000000000000000000000",
"market_order": false,
"client_order_id": 1,
"time_in_force": "GTC",
"post_only": false,
"deadline": "1645253261237547000"
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
"1"
Place a buy order.
Request
See place_ask
Response
See place_ask
cancel_order
near call v2_0_2.perp.spin-fi.testnet cancel_order \
'{
"market_id": 1,
"order_id": "1",
"deadline": "1645253261237547000"
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
{}
Cancel an order for a specified market by order ID.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | Market ID |
| order_id | true | string | Order ID |
| deadline | true | string | Transaction execution deadline. Time in nanoseconds. |
cancel_orders
near call v2_0_2.perp.spin-fi.testnet cancel_orders \
'{
"market_id": 1,
"limit": 100,
"deadline": "1645253261237547000"
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
1
Cancel all user orders for a specified market.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | false | number | Optional market ID. Orders from all markets would be dropped if not specified |
| limit | false | number | Optional limit for number of orders to be dropped |
| deadline | true | string | Transaction execution deadline. Time in nanoseconds. |
Response
| Type | Description |
|---|---|
| number | Number of cancelled orders |
batch_ops
near call v2_0_2.perp.spin-fi.testnet batch_ops \
'{
"ops": [
{
"market_id": 1,
"drop": ["23"],
"place": [
{
"price": "2000000000000000000000000",
"quantity": "1000000000000000000000000",
"market_order": false,
"order_type": "Bid",
"client_order_id": 1
}
]
}
],
"deadline": "1667942545196000000"
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
{}
Method allows you to perform many operations within a single transaction.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| ops | true | array of objects | Enumeration of markets and operations on them |
| › market_id | true | number | Market ID |
| › drop | false | array of strings | Contains a list of orders to be drop |
| › place | false | array of objects | Contains a list of orders to place. See place_ask |
| deadline | true | string | Transaction execution deadline. Time in nanoseconds. |
check_position
near view v2_0_2.perp.spin-fi.testnet check_position \
'{
"liquidated": "bob.near",
"liquidator": "alice.near",
"market_id": 1,
"liquidation": "10000000000000000000000",
"liquidate_orders": false
}'
Response:
{
"orders": [{"market_id": 1, "id":"1"}],
"position": {
"Ok": {
"liquidated_update": {
"size": "10000000000000000000000000",
"entry_price": "4200000000000000000000000",
"position_type": "Long"
},
"liquidator_update": {
"size": "10000000000000000000000000",
"entry_price": "4200000000000000000000000",
"position_type": "Short"
},
"liquidator_profit": "630000000000000000000000",
"insurance_fund": "420000000000000000000000"
}
}
}
The method checks the possibility to liquidate the position and returns liquidation parameters. This is dry run version of this method.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| liquidated | true | string | Account ID of the user to be liquidated |
| liquidator | false | string, null | Account ID of the liquidator. Optional |
| market_id | true | number | Market ID |
| liquidation | true | string | Desired liquidation size |
| liquidate_orders | true | boolean | Try to cancel order before liquidate position |
Response
TODO!
liquidate_position
near call v2_0_2.perp.spin-fi.testnet liquidate_position \
'{
"liquidated": "bob.near",
"market_id": 1,
"liquidation": "10000000000000000000000",
"deadline": "1745253261237547000",
"close_position": null
}' \
--accountId <YOUR_ACCOUNT_ID> \
--gas=300000000000000
Response:
{
"orders": [{"market_id": 1, "id":"1"}],
"position": {
"Ok": {
"liquidated_update": {
"size": "10000000000000000000000000",
"entry_price": "4200000000000000000000000",
"position_type": "Long"
},
"liquidator_update": {
"size": "10000000000000000000000000",
"entry_price": "4200000000000000000000000",
"position_type": "Short"
},
"liquidator_profit": "630000000000000000000000",
"insurance_fund": "420000000000000000000000"
}
}
}
Tries to liquidate the position.
Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| liquidated | true | string | Account ID of the user to be liquidated |
| market_id | true | number | Market ID |
| liquidation | true | string | Desired liquidation size |
| close_position | true | boolean, null | Allows you to place an order opposite to the liquidated position. |
Response
TODO!
Gateway API
Mainnet
WS endpoint mainnet url wss://mainnet.api.spin.fi/perp/v1/ws
JSON-RPC
Request
Example of a request message:
{
"jsonrpc": "2.0",
"method": "method",
"params": [0],
"id": 123
}
| Name | Type | Description |
|---|---|---|
| jsonrpc | string | Version of JSON-RPC spec: "2.0" |
| id | string or number | Subscription ID. Response will contain the same ID |
| method | string | Method name |
| params | [object] | This values used as method parameters |
Response
Example of a response message:
{
"jsonrpc": "2.0",
"id": 123,
"result": 0
}
| Name | Type | Description |
|---|---|---|
| jsonrpc | string | Version of JSON-RPC spec: "2.0" |
| id | string or number | Subscription ID from the request |
| result | object | Output value |
Subscription Management
subscribe
Example of a request message:
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": [
[
"channel1|params",
"channel2|params",
...
]
],
"id": 0
}
This is a subscribe method that allows you to connect to several channels.
Parameters
| Parameter | Type | Enum | Description |
|---|---|---|---|
| 0 | [string] | Array of channels to subscribe |
Example of a response message:
{
"jsonrpc": "2.0",
"id": 0,
"result": "b8143045-70d0-4926-8a5a-945b5179040a"
}
Request
| Name | Type | Description |
|---|---|---|
| jsonrpc | string | Version of JSON-RPC spec: "2.0" |
| id | string or number | ID from the request |
| result | string | Subscription ID. Use to unsubscribe from channels (see below) |
unsubscribe
Example of a request message:
{
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": [
"b8143045-70d0-4926-8a5a-945b5179040a"
],
"id": 0
}
This is a unsubscribe method that allows you to disconnect from one channel by subscription ID.
Parameters
| Parameter | Type | Enum | Description |
|---|---|---|---|
| 0 | string | Subscription ID to unsubscribe |
Example of a response message:
{
"jsonrpc": "2.0",
"result": true,
"id": 0
}
Response
| Name | Type | Description |
|---|---|---|
| jsonrpc | string | Version of JSON-RPC spec: "2.0" |
| id | string or number | ID from the request |
| result | boolean | Result of the unsubscribe |
Subscriptions
trades|{market_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"block_number": 77999930,
"maker_fee": "-14805000000000000000000",
"fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "744444",
"order_taker_id": "744463",
"price": "2869000000000000000000000",
"quantity": "29610000000000000000000000",
"side": "bid",
"taker_fee": "29610000000000000000000",
"taker_id": "2.user.testnet",
"ts": "1667923475436118450"
},
"meta": {
"channel": "trades|1"
}
},
"subscription": "c11d9e9d-937b-42e0-94bc-4a95dda9499d"
}
}
Subscribes to the trades stream of a particular market by it's id.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | ID of the market |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | Subscription id |
| result | object | |
| › data | object | |
| › › block_number | number | Block number in which the transaction was added |
| › › maker_fee | string | Comission amount from the maker side. If negative then rebate |
| › › fee_token_id | number | Token ID in which the maker paid the fee |
| › › maker_id | string | Near account ID of the maker |
| › › market_id | number | Market ID |
| › › order_maker_id | string | Matched order ID from the maker side |
| › › order_taker_id | string | Matched order ID from the taker side |
| › › price | string | Matching price in the quote currency |
| › › quantity | string | Matching quantity in the base currency |
| › › side | string | bid or ask |
| › › taker_fee | string | Comission amount from the taker side |
| › › taker_id | string | Near account id of the taker |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
orders|{market_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"average_price": "2869000000000000000000000",
"block_number": 78000028,
"client_order_id": null,
"market_id": 1,
"order_id": "744444",
"price": "2869000000000000000000000",
"quantity": "1337910000000000000000000000",
"remaining": "1233130000000000000000000000",
"side": "ask",
"status": "partially_filled",
"ts": "1667923604290135187",
"txn_hash": "HJGZ5p2Gj91hAtcepAa9sSQsaHk4cM5nGKaV94Kbx4Qp"
},
"meta": {
"channel": "orders|1"
}
},
"subscription": "f9828834-2a27-4292-9a41-d36efba9b3cd"
}
}
Subscribes to the all orders stream of a particular market by it's id.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | ID of the market |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | ID of the subscription |
| result | object | |
| › data | object | |
| › › account_id | string | Order owner near account ID |
| › › average_price | string | Average price of the order match. 0 if the order hasn't yet been filled at all |
| › › block_number | number | Block number in which the transaction was added |
| › › client_order_id | string, null | Custom order ID. Optionally set by the user when order placing |
| › › market_id | number | Market ID |
| › › order_id | string | Order ID. Set by contract. Unique identificator among all orders |
| › › price | string | Limit price of the order in the quote currency |
| › › quantity | string | Initial quantity of the order in base currency |
| › › remaining | string | Remaining order quantity to be executed in base currency |
| › › side | string | bid or ask |
| › › status | string | new, filled, partially_filled, cancelled |
| › › ts | string | Order update timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › › txn_hash | string | Transaction hash |
| › meta | object | |
| › › channel | string | Channel name |
bookL1|{market_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"ask": [
"2897000000000000000000000",
"1315640000000000000000000000"
],
"bid": [
"2890000000000000000000000",
"2303690000000000000000000000"
],
"ts": "1667923670989447017"
},
"meta": {
"channel": "bookL1|1"
}
},
"subscription": "f35dcfe7-2f84-4a29-a51a-dcc1e04581a6"
}
}
Subscribe to the orderbook L1 data. Notifications are sent every time when best bid or best ask were changed. That changes couldn't be generated more often than block is validated and added in near blockchain, but there can be multiple changes within one block. Messages order is guaranteed.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | ID of the market |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | object | |
| › › ask | [string, string] | [price, quantity] tuple |
| › › bid | [string, string] | See 'ask' field |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
bookL2|{market_id}|{?depth}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"asks": [
[
"2923000000000000000000000",
"1315580000000000000000000000"
],
[
"2934000000000000000000000",
"822230000000000000000000000"
]
],
"bids": [
[
"2916000000000000000000000",
"2283670000000000000000000000"
],
[
"2905000000000000000000000",
"1432700000000000000000000000"
]
],
"ts": "1667923722092839961"
},
"meta": {
"channel": "bookL2|1|2"
}
},
"subscription": "015517f1-391a-4616-998b-38390eae3e27"
}
}
Subscribe to the orderbook L2 data. L2 data consists a snapshot of the bids/asks prices and quantities with a specific depth. Notifications are sent every time an order book with specified depth is updated, but don't forget that each block in blockchain is generated approximately 1 second, so the average time of this type of notification approximately 1 second too. If there is no changes in orderbook notifications won't be sent.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | ID of the market |
| depth | false | number | The number of entries to return for bids and asks. If depth has an invalid value (i.e. 0, -1, 1.5) all bids and asks will be returned |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | ID of the subscription |
| result | object | |
| › data | object | |
| › › price_nodes | object | |
| › › › asks | array of [string, string] | Array of [price, quantity] tuples |
| › › › bids | array of [string, string] | See "asks" field |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
bookL3|{market_id}
Response:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"price_nodes": {
"asks": [
[
"2875000000000000000000000",
"2664000000000000000000000000"
],
[
"2886000000000000000000000",
"1665000000000000000000000000"
]
],
"bids": [
[
"2868000000000000000000000",
"2281710000000000000000000000"
],
[
"2858000000000000000000000",
"4980000000000000000000000"
]
]
},
"ts": "1667904821218813009"
},
"meta": {
"channel": "bookL3|1"
}
},
"subscription": "c1d8ffcc-fc4f-4da2-ba8c-ccb6e511c761"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"market_id": 1,
"price_node_changes": [
{
"price": "2865000000000000000000000",
"quantity": "26730000000000000000000000",
"side": "bid"
}
],
"ts": "1667904960555004021"
},
"meta": {
"channel": "bookL3|1"
}
},
"subscription": "c1d8ffcc-fc4f-4da2-ba8c-ccb6e511c761"
}
}
Subscribe to the orderbook L3 data. In response you receive an initial snapshot of the orderbook. Each next notification means absolutely quantity for a given price level changes. If quantity is 0, it means there are no orders for a given price level.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| market_id | true | number | ID of the market |
Response
| Name | Type | Description |
|---|---|---|
| subscription | string | ID of the subscription |
| result | object | |
| › data | object | |
| › › price_nodes | object | |
| › › › asks | array of [string, string] | Array of [price, quantity] tuples |
| › › › bids | array of [string, string] | See "asks" field |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | object | |
| › › market_id | number | ID of the market |
| › › price_node_changes | object | |
| › › › price | string | Level price inside orderbook |
| › › › quantity | quantity | Absolutely quantity for a given price level |
| › › › side | string | bid or ask |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
account|trades|{account_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"block_number": 78000234,
"maker_fee": "-1613700000000000000000000",
"maker_fee_token_id": 2,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "744713",
"order_taker_id": "744795",
"price": "2934000000000000000000000",
"quantity": "1100000000000000000000000000",
"side": "ask",
"taker_fee": "3227400000000000000000000",
"taker_fee_token_id": 2,
"taker_id": "2.user.testnet",
"ts": "1667923879820301498"
},
"meta": {
"channel": "account|trades|user.testnet"
}
},
"subscription": "3fe23bac-a678-402e-b61d-50fe12b2e614"
}
}
Subscribes to the trades stream of a particular account by it's ID.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | true | string |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | ID of the subscription |
| result | object | |
| › data | object | |
| › › block_number | number | Block number in which the transaction was added |
| › › maker_fee | string | Comission amount from the maker side. If negative then rebate |
| › › maker_fee_token_id | number | Token ID in which the maker paid the fee |
| › › maker_id | string | Near account ID of the maker |
| › › market_id | number | Market ID |
| › › order_maker_id | string | Matched order ID from the maker side |
| › › order_taker_id | string | Matched order ID from the taker side |
| › › price | string | Matching price in the quote currency |
| › › quantity | string | Matching quantity in the base currency |
| › › side | string | bid or ask |
| › › taker_fee | string | Comission amount from the taker side |
| › › taker_fee_token_id | string | Token ID in which the taker paid the fee |
| › › taker_id | string | Near account id of the taker |
| › › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › meta | object | |
| › › channel | string | Channel name |
account|orders|{account_id}
Response:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": [
{
"account_id": "user.testnet",
"average_price": "0",
"block_number": 78000240,
"client_order_id": null,
"created_at": "1667923887499519147",
"market_id": 1,
"order_id": "744796",
"price": "2907000000000000000000000",
"quantity": "2290730000000000000000000000",
"remaining": "2290730000000000000000000000",
"side": "bid",
"status": "new",
"txn_hash": "BWAnUchxv1coRYXRMoxZ2vsPXvg9jiBXcjRcrxXE4UZE",
"updated_at": "1667923887499519147"
},
{
"account_id": "user.testnet",
"average_price": "0",
"block_number": 78000240,
"client_order_id": null,
"created_at": "1667923887499519147",
"market_id": 1,
"order_id": "744797",
"price": "2896000000000000000000000",
"quantity": "1437140000000000000000000000",
"remaining": "1437140000000000000000000000",
"side": "bid",
"status": "new",
"txn_hash": "BWAnUchxv1coRYXRMoxZ2vsPXvg9jiBXcjRcrxXE4UZE",
"updated_at": "1667923887499519147"
}
],
"meta": {
"channel": "account|orders|user.testnet"
}
},
"subscription": "41974e41-a720-4e17-8ff9-06ac3c3b7802"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"average_price": "0",
"block_number": 78000288,
"client_order_id": null,
"market_id": 1,
"order_id": "744817",
"price": "2943000000000000000000000",
"quantity": "1901920000000000000000000000",
"remaining": "1901920000000000000000000000",
"side": "ask",
"status": "new",
"ts": "1667923951503435633",
"txn_hash": "4H6HQS1g2U4Sxd8U94fwpD38mEBMvuV1rBEuFZnmBsMM"
},
"meta": {
"channel": "account|orders|user.testnet"
}
},
"subscription": "41974e41-a720-4e17-8ff9-06ac3c3b7802"
}
}
Subscribes to the all orders stream of a particular account by it's ID.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | true | string |
Response
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | array of object | |
| › › account_id | string | Order owner near account ID |
| › › average_price | string | Average price of the order match. 0 if the order hasn't yet been filled at all |
| › › block_number | number | Block number in which the transaction was added |
| › › client_order_id | string | Custom order ID. Optionally set by the user when order placing |
| › › market_id | number | Market ID |
| › › order_id | string | Order ID. Set by contract. Unique identificator among all orders |
| › › price | string | Limit price of the order in the quote currency |
| › › quantity | string | Initial quantity of the order in base currency |
| › › remaining | string | Remaining order quantity to be executed in base currency |
| › › side | string | bid or ask |
| › › status | string | new, filled, partially_filled, cancelled |
| › › created_at | string | Order creation timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › › updated_at | string | Last order update timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › › txn_hash | string | Transaction hash |
| › meta | object | |
| › › channel | string | Channel name |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | object | |
| › › account_id | string | |
| › › average_price | string | |
| › › block_number | number | |
| › › client_order_id | string | |
| › › market_id | number | |
| › › order_id | string | |
| › › price | string | |
| › › quantity | string | |
| › › remaining | string | |
| › › side | string | bid or ask |
| › › status | string | new, filled, partially_filled, cancelled |
| › › ts | string | Order update timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › › txn_hash | string | |
| › meta | object | |
| › › channel | string | Channel name |
account|balances|{account_id}
Response:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": [
{
"available": "2803065000000000000000000",
"reserved": "3567050000000000000000000000",
"token_id": 1
},
{
"available": "3794257181000000000000000000",
"reserved": "12486140330000000000000000000",
"token_id": 2
}
],
"meta": {
"channel": "account|balances|user.testnet"
}
},
"subscription": "58380487-63b5-4bdb-a573-685a808e242e"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"action": "buy",
"quantity": "5540400000000000000000000000",
"token_id": 2
},
"meta": {
"channel": "account|balances|user.testnet"
}
},
"subscription": "58380487-63b5-4bdb-a573-685a808e242e"
}
}
Subscribes to the balance changes stream of a particular account by it's ID.
Channel Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | true | string |
Response
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | array of object | |
| › › available | string | Available balance to trade |
| › › reserved | string | Locked balance in open orders |
| › › token_id | number | Token ID |
| › meta | object | |
| › › channel | string | Channel name |
Notification
| Name | Type | Description |
|---|---|---|
| subscription | string | |
| result | object | |
| › data | object | |
| › › account_id | string | |
| › › action | string | withdraw, deposit, reserve, release, buy, sell |
| › › quantity | string | |
| › › token_id | number | |
| › meta | object | |
| › › channel | string | Channel name |
Methods
ping
Request:
{
"jsonrpc": "2.0",
"method": "ping",
"params": [],
"id": 0
}
Response:
{
"jsonrpc": "2.0",
"result": "pong",
"id": 0
}
Health check method for gateway API.
get_trades
Response:
{
"jsonrpc": "2.0",
"result": [
{
"block_number": 78016624,
"id": 10000000000135505,
"maker_fee": "-761000000000000000000",
"fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751404",
"order_taker_id": "751450",
"price": "2626000000000000000000000",
"quantity": "580000000000000000000000",
"side": "ask",
"taker_fee": "1523000000000000000000",
"taker_id": "2.user.testnet",
"ts": "1667943987855748256"
},
{
"block_number": 78016512,
"id": 10000000000135504,
"maker_fee": "-147226000000000000000000",
"fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751404",
"order_taker_id": "751448",
"price": "2626000000000000000000000",
"quantity": "112130000000000000000000000",
"side": "ask",
"taker_fee": "294453000000000000000000",
"taker_id": "2.user.testnet",
"ts": "1667943852292365268"
},
{
"block_number": 78016467,
"id": 10000000000135503,
"maker_fee": "-1055000000000000000000",
"fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751409",
"order_taker_id": "751447",
"price": "2633000000000000000000000",
"quantity": "2110000000000000000000000",
"side": "bid",
"taker_fee": "2110000000000000000000",
"taker_id": "2.user.testnet",
"ts": "1667943801961525287"
}
],
"id": 0
}
Returns the latest trades that have occurred for instruments in a specific market ID.
Parameters
| # | Type | Description |
|---|---|---|
| 0. | number | Market ID |
| 1. | number | Limit |
| 2. | number | Offset |
Response
| Name | Type | Description |
|---|---|---|
| result | array of objects | |
| › id | number | Unique ID of the trade among specified market |
| › block_number | number | Block number in which the transaction was added |
| › maker_fee | string | Comission amount from the maker side. If negative then rebate |
| › fee_token_id | number | number |
| › maker_id | string | Near account ID of the maker |
| › market_id | number | Market ID |
| › order_maker_id | string | Matched order ID from the maker side |
| › order_taker_id | string | Matched order ID from the taker side |
| › price | string | Matching price in the quote currency |
| › quantity | string | Matching quantity in the base currency |
| › side | string | bid or ask |
| › taker_fee | string | Comission amount from the taker side |
| › taker_id | string | Near account ID of the taker |
| › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
get_user_trades
Response:
{
"jsonrpc": "2.0",
"result": [
{
"block_number": 78016624,
"id": 10000000000135505,
"maker_fee": "-761000000000000000000",
"maker_fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751404",
"order_taker_id": "751450",
"price": "2626000000000000000000000",
"quantity": "580000000000000000000000",
"side": "ask",
"taker_fee": "1523000000000000000000",
"taker_fee_token_id": 1,
"taker_id": "2.user.testnet",
"ts": "1667943987855748256"
},
{
"block_number": 78016512,
"id": 10000000000135504,
"maker_fee": "-147226000000000000000000",
"maker_fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751404",
"order_taker_id": "751448",
"price": "2626000000000000000000000",
"quantity": "112130000000000000000000000",
"side": "ask",
"taker_fee": "294453000000000000000000",
"taker_fee_token_id": 1,
"taker_id": "2.user.testnet",
"ts": "1667943852292365268"
},
{
"block_number": 78016467,
"id": 10000000000135503,
"maker_fee": "-1055000000000000000000",
"maker_fee_token_id": 1,
"maker_id": "1.user.testnet",
"market_id": 1,
"order_maker_id": "751409",
"order_taker_id": "751447",
"price": "2633000000000000000000000",
"quantity": "2110000000000000000000000",
"side": "bid",
"taker_fee": "2110000000000000000000",
"taker_fee_token_id": 1,
"taker_id": "2.user.testnet",
"ts": "1667943801961525287"
}
],
"id": 0
}
Returns the latest trades that have occurred for a specific account ID (including either taker or maker).
Parameters
| # | Type | Description |
|---|---|---|
| 0. | string | Account ID |
| 1. | number | Limit |
| 2. | number | Offset |
Response
| Name | Type | Description |
|---|---|---|
| result | array of objects | |
| › id | number | Unique ID of the trade among specified market |
| › block_number | number | Block number in which the transaction was added |
| › maker_fee | string | Comission amount from the maker side. If negative then rebate |
| › maker_fee_token_id | number | number |
| › maker_id | string | Near account ID of the maker |
| › market_id | number | Market ID |
| › order_maker_id | string | Matched order ID from the maker side |
| › order_taker_id | string | Matched order ID from the taker side |
| › price | string | Matching price in the quote currency |
| › quantity | string | Matching quantity in the base currency |
| › side | string | bid or ask |
| › taker_fee | string | Comission amount from the taker side |
| › taker_fee_token_id | string | Token ID in which the taker paid the fee |
| › taker_id | string | Near account ID of the taker |
| › ts | string | Timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
get_orders_history
Response:
{
"jsonrpc": "2.0",
"result": [
{
"account_id": "user.testnet",
"average_price": "10000",
"block_number": 86373460,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "5",
"price": "10000",
"quantity": "10000000000000000000000",
"remaining": "0",
"side": "ask",
"status": "filled",
"txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
"updated_at": "1649164215000000000"
},
{
"account_id": "user.testnet",
"average_price": "20000",
"block_number": 86373460,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "6",
"price": "20000",
"quantity": "10000000000000000000000",
"remaining": "0",
"side": "ask",
"status": "filled",
"txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
"updated_at": "1649164215000000000"
},
{
"account_id": "user.testnet",
"average_price": "20000",
"block_number": 86373460,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "7",
"price": "20000",
"quantity": "20000000000000000000000",
"remaining": "0",
"side": "bid",
"status": "filled",
"txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
"updated_at": "1649164215000000000"
}
],
"id": 0
}
Returns history of orders that have been partially or fully filled or cancelled.
Parameters
| # | Type | Description |
|---|---|---|
| 0. | number | Market ID |
| 1. | string | Account ID |
| 2. | number | Limit |
| 3. | number | Offset |
Response
| Name | Type | Description |
|---|---|---|
| result | array of objects | |
| › account_id | string | Order owner near account ID |
| › average_price | string | Average price of the order match. 0 if the order hasn't yet been filled at all |
| › block_number | number | Block number in which the transaction was added |
| › client_order_id | string | Custom order ID. Optionally set by the user when order placing |
| › market_id | number | Market ID |
| › order_id | string | Order ID. Set by contract. Unique identificator among all orders |
| › price | string | Limit price of the order in the quote currency |
| › quantity | string | Initial quantity of the order in base currency |
| › remaining | string | Remaining order quantity to be executed in base currency |
| › side | string | bid or ask |
| › status | string | new, filled, partially_filled, cancelled |
| › created_at | string | Order creation timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › updated_at | string | Last order update timestamp in nanoseconds (1 second = 1 * 10^9 nanosecond) |
| › txn_hash | string | string |
get_candles
Response:
{
"jsonrpc": "2.0",
"result": [
{
"base_volume": "19620000000000000000000000",
"close": "3139000000000000000000000",
"close_ts": "1667264400000000000",
"high": "3139000000000000000000000",
"low": "3102000000000000000000000",
"open": "3128000000000000000000000",
"open_ts": "1667260800000000000",
"quote_volume": "61255590000000000000000000"
},
{
"base_volume": "73000000000000000000000000",
"close": "3135000000000000000000000",
"close_ts": "1667268000000000000",
"high": "3135000000000000000000000",
"low": "3120000000000000000000000",
"open": "3120000000000000000000000",
"open_ts": "1667264400000000000",
"quote_volume": "227860050000000000000000000"
}
],
"id": 0
}
Returns history of candles to use in OHLC chart.
Parameters
| # | Type | Enum | Description |
|---|---|---|---|
| 0. | number | Market ID | |
| 1. | number | 1, 3, 5, 10, 15, 30, 60, 120, 180, 240, 480, 720, 1440 |
Interval in minutes |
| 2. | number | From (timestamp in nanoseconds) | |
| 3. | number | To (timestamp in nanoseconds) | |
| 4. | number | Limit | |
| 5. | number | Offset |
Response
| Name | Type | Description |
|---|---|---|
| result | array of objects | |
| › high | string | Highest price for the specified interval |
| › low | string | Lowest price for the specified interval |
| › open | string | Open price for the specified interval |
| › close | string | Close price for the specified interval |
| › quote_volume | string | Total volume in quote currencies for the specified |
| › base_volume | string | Total volume in base currencies for the specified |
| › open_ts | string | Open timestamp of the specified interval in nanoseconds (inclusive) |
| › close_ts | string | Close timestamp of the specified interval in nanoseconds (exclusive) |
Errors
Contract errors
| Error String | Meaning |
|---|---|
| TODO | Coming soon |
Gateway errors
Coming soon!
Events
/// Perp contract events.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub enum PerpEvent {
Currency(Currency),
MaxDeposit(MaxDeposit),
Whitelist(Whitelist),
CreateMarket(CreateMarket),
MarketOptions(MarketOptions),
IndexPrice(IndexPrice),
FundingRate(FundingRate),
Balance(Balance),
Orderbook(Orderbook),
Order(Order),
Trade(Trade),
Position(Position),
Liquidation(Liquidation),
}
impl EventTrait for PerpEvent {}
/// Set currency event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Currency {
/// Currency address.
pub address: String,
/// Decimals.
pub decimals: u8,
/// Symbol.
pub symbol: String,
}
/// Set max deposit event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct MaxDeposit {
/// Max deposit amount.
pub max_deposit: Option<u128>,
}
/// Add whitelist event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Whitelist {
/// List of market makers without volume limits.
pub account_ids: Vec<String>,
}
/// Market created event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct CreateMarket {
/// Market id.
pub market_id: u16,
/// Market symbol.
pub symbol: String,
/// Max leverage.
pub max_leverage: u16,
}
/// Market option updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct MarketOptions {
/// Market id.
pub market_id: u16,
/// Market availability data.
pub availability: MarketAvailabilityEventData,
/// Market limits data.
pub limits: MarketLimitsEventData,
/// Market fees data.
pub fees: MarketFeesEventData,
}
/// Market option updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct MarketAvailabilityEventData {
/// If market allows order placing.
pub allow_place: bool,
/// If market allows order cancelling.
pub allow_cancel: bool,
}
/// Market option updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct MarketLimitsEventData {
/// Tick size.
pub tick_size: u128,
/// Step size.
pub step_size: u128,
/// Minimum base quantity for order.
pub min_base_quantity: u128,
/// Maximum base quantity for order.
pub max_base_quantity: u128,
/// Maximum quote quantity for order.
pub min_quote_quantity: u128,
/// Maximum quote quantity for order.
pub max_quote_quantity: u128,
/// Maximum bid orders count per user.
pub max_bid_count: u32,
/// Maximum ask orders count per user.
pub max_ask_count: u32,
/// Maximum orders to match per transaction.
pub max_match_count: usize,
}
/// Market option updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct MarketFeesEventData {
/// Maker fee.
pub maker_fee: u128,
/// Taker fee.
pub taker_fee: u128,
/// Decimal.
pub decimal: u8,
/// If maker fee is a rebate.
pub is_rebate: bool,
}
/// Index and mid prices added event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct IndexPrice {
/// Market id.
pub market_id: u16,
/// Index price.
pub index_price: u128,
/// Mid price.
pub mid_price: Option<u128>,
/// Tick.
pub tick: u64,
}
/// Funding rate added event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct FundingRate {
/// Market id.
pub market_id: u16,
/// Funding rate.
pub rate: u128,
/// Funding rate sign.
pub is_positive: bool,
/// Average index price.
pub avg_index_price: u128,
/// Epoch.
pub epoch: u64,
}
/// Balance updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Balance {
/// User id.
pub user_id: u16,
/// Amount.
pub amount: u128,
/// Is income or outcome.
pub increased: bool,
/// Type of change.
pub change_type: BalanceChangeType,
}
/// Balance change event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub enum BalanceChangeType {
/// External change - deposit or withdraw.
External,
/// Executing order.
Trade(u128),
/// Position liquidation.
Liquidation(u16),
}
/// Orderbook changed event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Orderbook {
/// Market id.
pub market_id: u16,
/// Price.
pub price: u128,
/// Quantity.
pub quantity: u128,
/// Order side.
pub side: OrderSide,
}
/// Order changed event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Order {
/// Market id.
pub market_id: u16,
/// Order id.
pub order_id: u128,
/// User id.
pub user_id: u16,
/// Price.
pub price: u128,
/// Average price
pub average_price: u128,
/// Quantity.
pub quantity: u128,
/// Remaining quantity.
pub remaining: u128,
/// Order side.
pub side: OrderSide,
/// Order kind.
pub kind: OrderKind,
/// Order status.
pub status: OrderStatus,
/// Client order identifier.
pub client_order_id: Option<u32>,
/// Time-in-force parameter
pub time_in_force: TimeInForce,
}
/// Trade occured event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Trade {
/// Market id.
pub market_id: u16,
/// Maker order identifier.
pub maker_order_id: u128,
/// Taker order identifier.
pub taker_order_id: u128,
/// Maker fee amount.
pub maker_fee: u128,
/// Taker fee amount.
pub taker_fee: u128,
/// Is rebate for maker.
pub is_maker_fee_rebate: bool,
/// Price.
pub price: u128,
/// Quantity.
pub quantity: u128,
/// Order side.
pub side: OrderSide,
}
/// Position updated event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Position {
/// Market id.
pub market_id: u16,
/// User id.
pub user_id: u16,
/// Total size of the position.
pub size: u128,
/// Entry price.
pub entry_price: u128,
/// Position type.
pub position_type: PositionType,
/// Creation time.
pub created_at: u64,
/// Last update time.
pub updated_at: u64,
}
/// Liquidation occured event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct Liquidation {
/// Market id.
pub market_id: u16,
/// Liquidated user id.
pub liquidated_user_id: u16,
/// Liquidator user id.
pub liquidator_user_id: u16,
/// Liquidator rebate (1.5%).
pub liquidator_rebate: u128,
/// Rebate to contract fund (1%).
pub fund_rebate: u128,
/// Size.
pub size: u128,
}
/// Contract log.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct EventsData<E: EventTrait> {
/// Identifier.
pub id: u64,
/// Account map.
pub accounts: HashMap<AccountId, u16>,
/// Events.
pub events: Vec<E>,
}
To be informed about some changes inside DEX we use standart way for NEAR Protocol - events.
Example
Assume you have that log string
AQBMAQAAeAFtUb1LAzEc/aUWWiuCKNLBD4qTij163l3SmzwRnArCubg45NKcOFSLbuJQXKQI4tA/QBAKjtLFycXNLxTEwcnZpeLgqCaptVzakK/38uPlveTyLQWyxcTkiYF5LrAcii3C3SILicUFwRzHDfA8Nakd2pxbOeLaOCQUm3nGuckCm9sOyfOgSBAMCpWyaeyWN0slY4vTHYCkoFIIsg8Jsel0Q8MAmZuZg6fnJWlGlXm11fjZ+WFcAUAApxcbx4X3yTGxbXG1k9j03OzRkEJo4I//ev1cXKt691lJr/vDH3W6/90YbZ2iF3dkZXvZSbO7H1a4xWnlKno1QrrZ/m7/Ulw3pOOK/zi112yYMCGrASpXCxn/ulpvjiuM+gAS0lY0KSD9bUQyWQaRvF3v0U7UXoVpXUiq6CZ1rN+irP5PCMT/JHvpaOF+ATcOc6w=.
To make it more readable you need to decode it using base64 format and need to deserialize result using events scheme. The result will be presented as EventsData<PerpEvent>.