Introduction
This documentation describes how to interact with the Spin Spot DEX. 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 currencies and markets info, get deposits, get orderbook, get orders). The second section describes getting data via the API. 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.
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": "'user.testnet'"}'
near view usdc.spin-fi.testnet storage_balance_bounds
near call usdc.spin-fi.testnet storage_deposit '' --accountId user.testnet --amount <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 user.testnet --amount 0.000000000000000000000002
near view airdrop.spin-fi.testnet cool_down '{"account": "'user.testnet'", "token": "'usdc.spin-fi.testnet'"}'
near view usdc.spin-fi.testnet ft_balance_of '{"account_id": "'user.testnet'"}'
Spot Contract API
Use near call
to call contract methods.
Testnet
Contract is deployed to NEAR blockchain testnet account spot.spin-fi.testnet
and can be viewed here.
Mainnet
Contract is deployed to NEAR blockchain mainnet account spot.spin-fi.near
and can be viewed here.
Spot Contract API
Markets
get_currencies
near view spot.spin-fi.testnet get_currencies \
'{
"limit": 100,
"offset": 0
}'
Response:
[
{
"id": 1,
"address": "usdt.near",
"decimals": 24,
"symbol": "USDC",
"c_type": "FT",
"max_deposit": "1000000"
}
]
Returns all currencies supported by the contract.
Request
Parameter | Required | Type | Description |
---|---|---|---|
limit | false | number | Number of currencies to return. Default 100 |
offset | false | number | Offset in the list of currencies. Default 0 |
Response
Name | Type | Enum | Description |
---|---|---|---|
id | number | Currency ID | |
address | string | Currency ft contract address. "near.near" for near token | |
decimals | number | Currency decimals | |
symbol | string | Currency symbol | |
c_type | string | FT , Native |
Currency type. FT for ft contract or Native for near token |
max_deposit | string | Maximum amount of currency for deposit |
get_market
near view spot.spin-fi.testnet get_market \
'{
"market_id": 1
}'
Response:
{
"id": 1,
"ticker": "BTC/NEAR",
"base": {
"id": 1,
"symbol": "BTC",
"decimal": 8,
"address": "btc.testnet"
},
"quote": {
"id": 2,
"symbol": "NEAR",
"decimal": 24,
"address": "near.near"
},
"fees": {
"maker_fee": "5000",
"taker_fee": "10000",
"decimals": 6,
"is_rebate": true
},
"availability": {
"allow_place": true,
"allow_cancel": true
},
"limits": {
"tick_size": "10",
"step_size": "100000000000000000000000",
"min_base_quantity": "1000",
"max_base_quantity": "2000000000000000000000000",
"min_quote_quantity": "10",
"max_quote_quantity": "10000",
"max_bid_count": 25,
"max_ask_count": 25
}
}
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 |
ticker | string | Market ticker |
base | object | |
› symbol | string | Base currency symbol |
› decimal | string | Base currency decimal |
› address | string | Base currency address |
quote | object | See "base" field |
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 |
get_markets
near view spot.spin-fi.testnet get_markets
Response:
[
{
"id": 1,
"ticker": "BTC/NEAR",
"base": {
"id": 1,
"symbol": "BTC",
"decimal": 8,
"address": "btc.testnet"
},
"quote": {
"id": 2,
"symbol": "NEAR",
"decimal": 24,
"address": "near.near"
},
"fees": {
"maker_fee": "5000",
"taker_fee": "10000",
"decimals": 6,
"is_rebate": true
},
"availability": {
"allow_place": true,
"allow_cancel": true
},
"limits": {
"tick_size": "10",
"step_size": "100000000000000000000000",
"min_base_quantity": "1000",
"max_base_quantity": "2000000000000000000000000",
"min_quote_quantity": "10",
"max_quote_quantity": "10000",
"max_bid_count": 25,
"max_ask_count": 25
}
}
]
Returns all markets info supported by the contract.
Response
Type | Description |
---|---|
array of objects | Array of markets (See get_market ) |
get_orderbook
near view spot.spin-fi.testnet get_orderbook \
'{
"market_id": 1,
"limit": 10
}'
Response:
{
"ask_orders": [
{
"price": "100",
"quantity": "10"
}
],
"bid_orders": [
{
"price": "99",
"quantity": "1"
}
]
}
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" |
Balances
get_deposits
near view spot.spin-fi.testnet get_deposits \
'{
"account_id": "user.testnet"
}'
Response:
{
"spin_btc.testnet": "1000",
"near.near": "100000000000000000000000"
}
Returns account balannces by account ID.
Request
Parameter | Required | Type | Description |
---|---|---|---|
account_id | true | string | User account whose balance we are requesting |
Response
Name | Type | Description |
---|---|---|
token_address | string | Balance of token with this address |
... |
deposit_near
near call spot.spin-fi.testnet deposit_near \
--accountId user.testnet \
--amount 0.5
NEAR token is transferred by attaching them to a transaction. The attached amount will be credited to the trading account. To deposit Fungible Token use it's contract methods (detailed description in section)
Deposit FT
near call <TOKEN_ACCOUNT_ID> ft_transfer_call \
'{
"receiver_id": "spot.spin-fi.testnet",
"amount": "100000",
"msg": ""
}' \
--accountId <YOUR_ACCOUNT_ID> \
--amount 0.000000000000000000000001 \
--gas 300000000000000
To deposit tokens to your spot account you need to call ft_transfer_call
of the token contract and send
Request
Parameter | Required | Type | Description |
---|---|---|---|
receiver_id | true | string | Token recipient, the spot contract "spot.spin-fi.testnet" |
amount | true | string | Transfer amount |
msg | true | string | Should be empty |
withdraw
near call spot.spin-fi.testnet withdraw \
'{
"token": "near.near",
"amount": "1000"
}' \
--accountId <YOUR_ACCOUNT_ID> \
--gas=50000000000000
Withdraws token from the trading account to the user's account.
Request
Parameter | Required | Type | Description |
---|---|---|---|
token | true | string | Could be near.near for native NEAR withdrawal or any Fungible Token currency existing on contract market |
amount | true | string | Transfer amount |
50000000000000
gas must be applied to handle possible errors
Withdraw FT
near call spot.spin-fi.testnet withdraw \
'{
"token": "usdc.near",
"amount": "1000"
}' \
--accountId <YOUR_ACCOUNT_ID> \
--gas=50000000000000
--amount 0.000000000000000000000001
FT account registration:
near call <TOKEN_ACCOUNT_ID> storage_deposit '' \
--accountId <YOUR_ACCOUNT_ID> \
--amount 0.00125 # paste --amount value from `near view <TOKEN_ACCOUNT_ID> storage_balance_bounds`
Use the same method withdraw
as for NEAR withdrawal with the same parameters.
Orders
get_order
near view spot.spin-fi.testnet get_order \
'{
"market_id": 1,
"order_id": "1",
"account_id": "user.testnet"
}'
Response:
{
"id": "102",
"acc": "user.testnet",
"price": "800",
"average_price": "0",
"quantity": "1000000000000000000000000",
"remaining": "1000000000000000000000000",
"updated_at": "1649164215000000000",
"created_at": "1648838833603256735",
"expiration_time": "0",
"o_type": "Bid",
"client_order_id": null
}
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 | |
expiration_time | string | The timestamp of the order expiration | |
o_type | string | Ask , Bid |
Order type |
client_order_id | number | Optional non-unique client order ID |
get_orders
near view spot.spin-fi.testnet get_orders \
'{
"market_id": 1,
"account_id": "user.testnet"
}'
Response:
[
{
"id": "102",
"acc": "user.testnet",
"price": "800",
"average_price": "0",
"quantity": "1000000000000000000000000",
"remaining": "1000000000000000000000000",
"updated_at": "1649164215000000000",
"created_at": "1648838833603256735",
"expiration_time": "0",
"o_type": "Bid",
"client_order_id": null
}
]
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 spot.spin-fi.testnet place_ask \
'{
"market_id": 1,
"price": "1000000000000000000000000",
"quantity": "2000000000000000000000000",
"market_order": false,
"client_order_id": 1
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
"1"
Request
Place a sell order.
Parameter | Required | Type | Description |
---|---|---|---|
market_id | true | number | Market ID |
price | true | string | Order price. Decimal number with a fixed number of decimal places. The number of decimal places is equal to the precision of Quote currency. If market_order is True , the price is required anyway and is used as a slippage |
quantity | true | string | Quantity. Decimal number with a fixed number of decimal places. The number of decimal places is equal to the precision of Base currency |
market_order | true | boolean | A sign that the order is market |
client_order_id | false | number | Non-unique client order ID |
Response
Type | Description |
---|---|
string | ID of placed order |
place_bid
near call spot.spin-fi.testnet place_bid \
'{
"market_id": 1,
"price": "1000000000000000000000000",
"quantity": "2000000000000000000000000",
"market_order": false,
"client_order_id": 1
}' \
--accountId <YOUR_ACCOUNT_ID>
Response:
"1"
Place a buy order.
Request
See place_ask
Response
See place_ask
cancel_order
near call spot.spin-fi.testnet cancel_order \
'{
"market_id": 1,
"order_id": 1
}' \
--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 |
cancel_orders
'{
"market_id": 1,
"limit": 100
}'
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 |
Response
Type | Description |
---|---|
number | Number of cancelled orders |
batch_ops
near call spot.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
}
]
}
]
}' \
--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 |
Gateway API
Testnet
WS endpoint testnet url wss://testnet.api.spin.fi/spot/v1/ws
Mainnet
WS endpoint mainnet url wss://api.spin.fi/spot/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": 86368426,
"maker_fee": "0",
"maker_fee_token_id": 2,
"maker_id": "user.testnet",
"market_id": 1,
"order_maker_id": "1",
"order_taker_id": "2",
"price": "2000",
"quantity": "50000000000000000000000",
"side": "ask",
"taker_fee": "1",
"taker_fee_token_id": 2,
"taker_id": "2.user.testnet",
"ts": "1648719601362954574"
},
"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 |
› › 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 |
orders|{market_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"average_price": "0",
"block_number": 86372898,
"client_order_id": "",
"created_at": "1649168154029656834",
"market_id": 1,
"order_id": "5",
"price": "10000",
"quantity": "10000000000000000000000",
"remaining": "10000000000000000000000",
"side": "ask",
"status": "new",
"txn_hash": "HbqzPQgSAefnertNf1mHtKgnoRFskidRN7LYBDHoeGqp",
"updated_at": "1649168154029656834"
},
"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 | 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 | Transaction hash |
› meta | object | |
› › channel | string | Channel name |
bookL1|{market_id}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"ask": [
"20000",
"10000000000000000000000"
],
"bid": [],
"ts": "1648724722471719440"
},
"meta": {
"channel": "bookL1|1"
}
},
"subscription": "2d7ceeb1-91a7-4464-aa24-944909123801"
}
}
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 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": [
[
"10000",
"10000000000000000000000"
]
],
"bids": [],
"ts": "1648724152945746430"
},
"meta": {
"channel": "bookL2|1|5"
}
},
"subscription": "fa482014-cd67-4212-8162-77bbb3e3c67d"
}
}
Subscribe to the orderbook L2 data. L2 data consists a snapshot of the bids/asks prices and quantities with a specific depth. Right now notifications are sent every 100 millisecond, 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 | true | number | The number of entries to return for bids and asks |
Notification
Name | Type | Description |
---|---|---|
subscription | string | ID of the subscription |
result | object | |
› data | 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": {
"asks": [
[
"10000",
"10000000000000000000000"
]
],
"bids": [
[
"9000",
"10000000000000000000000"
]
],
"last_change_id": 4,
"ts": "1648724152945746430"
},
"meta": {
"channel": "bookL3|1"
}
},
"subscription": "90727d0d-03e9-4344-a451-5217088c39a8"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"id": 5,
"market_id": 1,
"price": "20000",
"quantity": "10000000000000000000000",
"side": "ask",
"ts": "1648724692134493780"
},
"meta": {
"channel": "bookL3|1"
}
},
"subscription": "90727d0d-03e9-4344-a451-5217088c39a8"
}
}
Subscribe to the orderbook L3 data. In response you receive an initial snapshot of the orderbook. There is a last_change_id
field that is used to validate integrity of the orderbook events sequence. Each next notification will have a sequentially increasing number by 1 in the id
field. Each notification means absolutely quantity
for a given price
level. 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 | |
› › asks | array of [string, string] | Array of [price, quantity] tuples |
› › bids | array of [string, string] | See "asks" field |
› › last_change_id | number | ID of the last changes inside the orderbook |
› › 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 | |
› › id | number | Change ID of the notification |
› › market_id | number | ID of the market |
› › 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": 86389143,
"maker_fee": "50000000000000000000",
"maker_fee_token_id": 1,
"maker_id": "user.testnet",
"market_id": 1,
"order_maker_id": "45",
"order_taker_id": "50",
"price": "10000",
"quantity": "10000000000000000000000",
"side": "bid",
"taker_fee": "100000000000000000000",
"taker_fee_token_id": 1,
"taker_id": "user.testnet",
"ts": "1648740501328080462"
},
"meta": {
"channel": "account|trades|user.testnet"
}
},
"subscription": "8711b451-7393-4383-8e18-63bc802bd326"
}
}
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",
"block_number": 86389303,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "53",
"price": "12500",
"quantity": "10000000000000000000000",
"remaining": "10000000000000000000000",
"side": "ask",
"status": "new",
"txn_hash": "H42axT3zuwWfxePkui8TsUzcdH9zsXHw1mVP5myPZgve",
"updated_at": "1649164215000000000"
},
{
"account_id": "user.testnet",
"block_number": 86389490,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "54",
"price": "13000",
"quantity": "10000000000000000000000",
"remaining": "10000000000000000000000",
"side": "ask",
"status": "new",
"txn_hash": "B6SymPVPcoa2z2ymxZJQw2TnKiKjYEwEVpZiwQ2rtSbX",
"updated_at": "1649164215000000000"
}
],
"meta": {
"channel": "account|orders|user.testnet"
}
},
"subscription": "80a8dd2d-9d9a-4805-8d62-cf6673e8cd11"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"average_price": "0",
"block_number": 86389490,
"client_order_id": "",
"created_at": "1649164215000000000",
"market_id": 1,
"order_id": "54",
"price": "13000",
"quantity": "10000000000000000000000",
"remaining": "10000000000000000000000",
"side": "ask",
"status": "new",
"ts": "1648740855475097139",
"txn_hash": "B6SymPVPcoa2z2ymxZJQw2TnKiKjYEwEVpZiwQ2rtSbX",
"updated_at": "1649164215000000000"
},
"meta": {
"channel": "account|orders|user.testnet"
}
},
"subscription": "66d91663-908d-4f27-aa99-1fef305ed6b5"
}
}
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 , 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 | 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 , 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 | |
› meta | object | |
› › channel | string | Channel name |
account|balances|{account_id}
Response:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": [
{
"available": "10000",
"reserved": "0",
"token_id": 2
},
{
"available": "4999450000000000000000000",
"reserved": "550000000000000000000",
"token_id": 1
}
],
"meta": {
"channel": "account|balances|user.testnet"
}
},
"subscription": "14fe741d-c5be-4b38-b790-e1d61c0f0821"
}
}
Notification:
{
"jsonrpc": "2.0",
"method": "subscription",
"params": {
"result": {
"data": {
"account_id": "user.testnet",
"action": "deposit",
"id": 143,
"quantity": "1000000000000000000000000",
"token_id": 1
},
"meta": {
"channel": "account|balances|user.testnet"
}
},
"subscription": "14fe741d-c5be-4b38-b790-e1d61c0f0821"
}
}
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 |
› › id | number | |
› › 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": 86368426,
"id": 0,
"maker_fee": "0",
"maker_id": "user.testnet",
"market_id": 1,
"order_maker_id": "1",
"order_taker_id": "2",
"price": "2000",
"quantity": "50000000000000000000000",
"side": "ask",
"taker_fee": "1",
"taker_id": "2.user.testnet",
"ts": "1648719601362954574"
},
{
"block_number": 86368835,
"id": 1,
"maker_fee": "0",
"maker_id": "user.testnet",
"market_id": 1,
"order_maker_id": "3",
"order_taker_id": "4",
"price": "2000",
"quantity": "50000000000000000000000",
"side": "ask",
"taker_fee": "1",
"taker_id": "2.user.testnet",
"ts": "1648720010615061808"
},
{
"block_number": 86373460,
"id": 2,
"maker_fee": "50000000000000000000",
"maker_id": "user.testnet",
"market_id": 1,
"order_maker_id": "5",
"order_taker_id": "7",
"price": "10000",
"quantity": "10000000000000000000000",
"side": "bid",
"taker_fee": "100000000000000000000",
"taker_id": "2.user.testnet",
"ts": "1648724722471719440"
}
],
"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 |
› 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": "50000000000000000000000",
"close": "2000",
"close_ts": "1648720200000000000",
"high": "2000",
"low": "2000",
"open": "2000",
"open_ts": "1648719900000000000",
"quote_volume": "100000000000000000000000000"
},
{
"base_volume": "40000000000000000000000",
"close": "10000",
"close_ts": "1648725000000000000",
"high": "20000",
"low": "10000",
"open": "10000",
"open_ts": "1648724700000000000",
"quote_volume": "600000000000000000000000000"
},
{
"base_volume": "10000000000000000000000",
"close": "10000",
"close_ts": "1648725300000000000",
"high": "10000",
"low": "10000",
"open": "10000",
"open_ts": "1648725000000000000",
"quote_volume": "100000000000000000000000000"
}
],
"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) |