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

RPC protocol

JS lib

Markets

`get_currencies`

near view spot.spin-fi.testnet get_currencies \
'{
  "limit": 100,
  "offset": 0
}'

[
  {
    "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
}'

{
  "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

[
  {
    "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
}'

{
  "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"
}'

{
  "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 as a receiver. You also need to pay for the transfer and attach 1 yoctoⓃ.

Calling ft_transfer on token contract won't call the successfull deposit callback on spot contract, so the funds would be lost!

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

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.

You'll need to register your account on FT contract first (due to NEP-145 specification). This can be done with storage_deposit method

Orders

`get_order`

near view spot.spin-fi.testnet get_order \
'{
  "market_id": 1,
  "order_id": "1",
  "account_id": "user.testnet"
}'

{
  "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"
}'

[
  {
    "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>

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

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

{}

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
}'

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>

{}

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

{
    "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

{
    "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`

{
    "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

{
    "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`

{
    "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

{
    "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}`

{
    "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}`

{
    "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}`

{
    "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}`

{
    "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}`

{
    "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"
    }
}

{
    "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}`

{
    "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}`

{
    "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"
    }
}

{
    "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}`

{
    "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"
    }
}

{
    "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`

{
    "jsonrpc": "2.0",
    "method": "ping",
    "params": [],
    "id": 0
}

{
    "jsonrpc": "2.0",
    "result": "pong",
    "id": 0
}

Health check method for gateway API.

`get_trades`

{
    "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_user_trades`

{
    "jsonrpc": "2.0",
    "result": [
        {
            "block_number": 91799490,
            "id": 124571,
            "maker_fee": "500000000000000000000",
            "maker_id": "2.user.testnet",
            "market_id": 1,
            "order_maker_id": "181153",
            "order_taker_id": "181190",
            "price": "510",
            "quantity": "1000000000000000000000000",
            "side": "bid",
            "taker_fee": "1000000000000000000000",
            "taker_id": "user.testnet",
            "ts": "1654606880840091887"
        },
        {
            "block_number": 91468066,
            "id": 117310,
            "maker_fee": "0",
            "maker_id": "user.testnet",
            "market_id": 2,
            "order_maker_id": "171921",
            "order_taker_id": "172022",
            "price": "543",
            "quantity": "1000000000000000000000000",
            "side": "ask",
            "taker_fee": "0",
            "taker_id": "2.user.testnet",
            "ts": "1654247589890469196"
        }
    ],
    "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_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_orders_history`

{
    "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`

{
    "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)