NAV
shell

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

RPC protocol

JS lib

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 view 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

Testnet

WS endpoint testnet url wss://testnet.api.spin.fi/perp/v1/ws

Mainnet

WS endpoint mainnet url wss://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, cancelled or expired.

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, expired
  ›  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!