NAV
shell

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

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