Introduction

This documentation describes how to interact with the Spin DEX Spot. 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 Gateway API. Gateway API is an off-chain service that collects and aggregates the results of execution of operations on a smart contract and provides convenient endpoints for receiving them. All API methods are called through JSON-RPC 2.0 protocol via websocket.

Changelog

2022-11-08

Small changes that break backward compatibility.

Endpoint was changed: wss://api.spin.fi/spot/v1/ws -> wss://mainnet.api.spin.fi/spot/v1/ws.
Subscriptions orders|<market_id>: replace created_at, updated_at fields with ts in notifications.
Subscriptions account|orders|<account_id>: replace created_at, updated_at fields with ts only in notifications (not response).
Subscriptions bookL3|<market_id>: add asks and bids fields to the price_nodes field in response.
Subscriptions bookL3|<market_id>: add price_node_changes field in notifications that aggregated all price node changes within one block.
Subscriptions bookL3|<market_id>: remove last_change_id field, message order is guaranteed.
Gateway API: maker_fee, taker_fee, price, average_price, quantity, remaining, ask, bid, asks, bids, available, reserved fields have 24 decimals.

Decimals

Contract Decimals

> near view usdc.spin-fi.testnet ft_metadata
{
  spec: 'ft-1.0.0',
  name: 'Circle USD',
  symbol: 'USDC',
  icon: null,
  reference: null,
  reference_hash: null,
  decimals: 2  # <-- pay attention
}

> near view v1.spot.spin-fi.testnet get_order '{"market_id": 1, "order_id": "1", "account_id": "user.testnet"}'
{
  "id": "1",
  "acc": "user.testnet",
  "price": "800",  # <-- decimals = 2, because `usdc.spin-fi.testnet` token
  "average_price": "0",
  "quantity": "1000000000000000000000000",  # <-- decimals = 24, because native NEAR
  "remaining": "1000000000000000000000000",
  "updated_at": "1649164215000000000",
  "created_at": "1648838833603256735",
  "o_type": "Bid",
  "client_order_id": null
}

All numerical values when working with the contract are integers but actually are floats. Here are some of fields, but not all: price, average_price, quantity, remaining and etc. The contract developer have to convert integer to float by himself. For v1.spot.spin-fi.testnet / spot.spin-fi.near contracts the position of the decimal point depends on the value of the decimals parameter of the token to which the number itself refers, or this decimals parameter is written explicitly. For native NEAR currency decimals value is 24.

See example below and to the right.

Considering the market NEAR/USDC. The price field refers to the usdc.spin-fi.testnet token with 2 decimals. So final value will be 8.0. The quantity value is set in the base currency (NEAR with 24 decimals). So final value will be 1.0.

Gateway API Decimals

All numerical values have 24 decimals or decimals will be written explicitly.

Faucet Testnet Contract API

Faucet Testnet Contract is used to get test USDC tokens. Contract is deployed to NEAR blockchain testnet account airdrop.spin-fi.testnet and can be viewed here.

Call next contract methods to get 1000 USDC every 24 hours.

near view usdc.spin-fi.testnet ft_balance_of '{"account_id": "'<YOUR_ACCOUNT_ID>'"}'
near view usdc.spin-fi.testnet storage_balance_bounds
near call usdc.spin-fi.testnet storage_deposit '' --accountId <YOUR_ACCOUNT_ID> --depositYocto <min> # where <min> - value from `storage_balance_bounds` command result
near call airdrop.spin-fi.testnet airdrop '{"token": "'usdc.spin-fi.testnet'"}' --gas=300000000000000 --accountId <YOUR_ACCOUNT_ID> --depositYocto 2
near view airdrop.spin-fi.testnet cool_down '{"account": "'<YOUR_ACCOUNT_ID>'", "token": "'usdc.spin-fi.testnet'"}'
near view usdc.spin-fi.testnet ft_balance_of '{"account_id": "'<YOUR_ACCOUNT_ID>'"}'

Spot Contract API

Use near call to call contract methods.

Testnet

Contract is deployed to NEAR blockchain testnet account v1.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 v1.spot.spin-fi.testnet get_currencies \
'{
  "limit": 100,
  "offset": 0
}'

[
  {
    "id": 2,
    "address": "usdc.spin-fi.testnet",
    "decimals": 2,
    "symbol": "USDC",
    "c_type": "FT",
    "max_deposit": "100000"
  },
  {
    "id": 1,
    "address": "near.near",
    "decimals": 24,
    "symbol": "NEAR",
    "c_type": "Native",
    "max_deposit": "200000000000000000000000000"
  }
]

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 v1.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
› id	number	Base currency symbol
› symbol	string	Base currency symbol
› decimal	number	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
› max_match_count	number	Limits on the maximum number of match within one transaction

`get_markets`

near view v1.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 v1.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 v1.spot.spin-fi.testnet get_deposits \
'{
  "account_id": "user.testnet"
}'

{
  "paras.fakes.testnet": "195017000000000000000",
  "aurora.fakes.testnet": "2998000000000000000",
  "ref.fakes.testnet": "1998000000000000000",
  "usdn.testnet": "100000000000000000000",
  "usdc.spin-fi.testnet": "115515",
  "near.near": "1739260000000000000000000",
}

Returns account balannces by account ID.

Request

Parameter	Required	Type	Description
account_id	true	string	User account whose balances we are requesting

Response

Name	Type	Description
token_address	string	Token balance at this address
...

`deposit_near`

near call v1.spot.spin-fi.testnet deposit_near \
--accountId <YOUR_ACCOUNT_ID> \
--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 usdc.spin-fi.testnet ft_transfer_call \
'{
  "receiver_id": "v1.spot.spin-fi.testnet", 
  "amount": "100000",
  "msg": ""
}' \
--accountId <YOUR_ACCOUNT_ID> \
--depositYocto 1 \
--gas 300000000000000

To deposit tokens to your spot account you need to call ft_transfer_call of the token contract and send v1.spot.spin-fi.testnet as a receiver_id parameter. 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 `v1.spot.spin-fi.testnet`)
amount	true	string	Transfer amount (given the decimals of the token)
msg	true	string	Should be empty

`withdraw`

near call v1.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
amount	true	string	Transfer amount (given the decimals of the token)

50000000000000 gas must be applied to handle possible errors

`Withdraw FT`

near call v1.spot.spin-fi.testnet withdraw \
'{
  "token": "usdc.spin-fi.testnet", 
  "amount": "1000"
}' \
--accountId <YOUR_ACCOUNT_ID> \
--gas=50000000000000
--depositYocto 1

near view usdc.spin-fi.testnet storage_balance_bounds
near call usdc.spin-fi.testnet storage_deposit '' --accountId <YOUR_ACCOUNT_ID> --depositYocto <min> # where <min> - value from `storage_balance_bounds` command result

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 v1.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",
  "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
o_type	string	`Ask`, `Bid`	Order type
client_order_id	number		Optional non-unique client order ID

`get_orders`

near view v1.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",
    "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 v1.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 v1.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 v1.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 v1.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

Mainnet

WS endpoint mainnet url wss://mainnet.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": 77999930,
                "maker_fee": "-14805000000000000000000",
                "maker_fee_token_id": 1,
                "maker_id": "1.user.testnet",
                "market_id": 1,
                "order_maker_id": "744444",
                "order_taker_id": "744463",
                "price": "2869000000000000000000000",
                "quantity": "29610000000000000000000000",
                "side": "bid",
                "taker_fee": "29610000000000000000000",
                "taker_fee_token_id": 1,
                "taker_id": "2.user.testnet",
                "ts": "1667923475436118450"
            },
            "meta": {
                "channel": "trades|1"
            }
        },
        "subscription": "c11d9e9d-937b-42e0-94bc-4a95dda9499d"
    }
}

Subscribes to the trades stream of a particular market by it's id.

Channel Parameters

Parameter	Required	Type	Description
market_id	true	number	ID of the market

Notification

Name	Type	Description
subscription	string	Subscription id
result	object
› data	object
› › block_number	number	Block number in which the transaction was added
› › maker_fee	string	Comission amount from the maker side. If negative then rebate
› › 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": "2869000000000000000000000",
                "block_number": 78000028,
                "client_order_id": null,
                "market_id": 1,
                "order_id": "744444",
                "price": "2869000000000000000000000",
                "quantity": "1337910000000000000000000000",
                "remaining": "1233130000000000000000000000",
                "side": "ask",
                "status": "partially_filled",
                "ts": "1667923604290135187",
                "txn_hash": "HJGZ5p2Gj91hAtcepAa9sSQsaHk4cM5nGKaV94Kbx4Qp"
            },
            "meta": {
                "channel": "orders|1"
            }
        },
        "subscription": "f9828834-2a27-4292-9a41-d36efba9b3cd"
    }
}

Subscribes to the all orders stream of a particular market by it's id.

Channel Parameters

Parameter	Required	Type	Description
market_id	true	number	ID of the market

Notification

Name	Type	Description
subscription	string	ID of the subscription
result	object
› data	object
› › account_id	string	Order owner near account ID
› › average_price	string	Average price of the order match. `0` if the order hasn't yet been filled at all
› › block_number	number	Block number in which the transaction was added
› › client_order_id	string, null	Custom order ID. Optionally set by the user when order placing
› › market_id	number	Market ID
› › order_id	string	Order ID. Set by contract. Unique identificator among all orders
› › price	string	Limit price of the order in the quote currency
› › quantity	string	Initial quantity of the order in base currency
› › remaining	string	Remaining order quantity to be executed in base currency
› › side	string	`bid` or `ask`
› › status	string	`new`, `filled`, `partially_filled`, `cancelled`
› › ts	string	Order update timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› › txn_hash	string	Transaction hash
› meta	object
› › channel	string	Channel name

`bookL1|{market_id}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "ask": [
                    "2897000000000000000000000",
                    "1315640000000000000000000000"
                ],
                "bid": [
                    "2890000000000000000000000",
                    "2303690000000000000000000000"
                ],
                "ts": "1667923670989447017"
            },
            "meta": {
                "channel": "bookL1|1"
            }
        },
        "subscription": "f35dcfe7-2f84-4a29-a51a-dcc1e04581a6"
    }
}

Subscribe to the orderbook L1 data. Notifications are sent every time when best bid or best ask were changed. That changes couldn't be generated more often than block is validated and added in near blockchain, but there can be multiple changes within one block. Messages order is guaranteed.

Channel Parameters

Parameter	Required	Type	Description
market_id	true	number	ID of the market

Notification

Name	Type	Description
subscription	string
result	object
› data	object
› › ask	[string, string]	`[price, quantity]` tuple
› › bid	[string, string]	See 'ask' field
› › ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› meta	object
› › channel	string	Channel name

`bookL2|{market_id}|{?depth}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "asks": [
                    [
                        "2923000000000000000000000",
                        "1315580000000000000000000000"
                    ],
                    [
                        "2934000000000000000000000",
                        "822230000000000000000000000"
                    ]
                ],
                "bids": [
                    [
                        "2916000000000000000000000",
                        "2283670000000000000000000000"
                    ],
                    [
                        "2905000000000000000000000",
                        "1432700000000000000000000000"
                    ]
                ],
                "ts": "1667923722092839961"
            },
            "meta": {
                "channel": "bookL2|1|2"
            }
        },
        "subscription": "015517f1-391a-4616-998b-38390eae3e27"
    }
}

Subscribe to the orderbook L2 data. L2 data consists a snapshot of the bids/asks prices and quantities with a specific depth. Notifications are sent every time an order book with specified depth is updated, but don't forget that each block in blockchain is generated approximately 1 second, so the average time of this type of notification approximately 1 second too. If there is no changes in orderbook notifications won't be sent.

Channel Parameters

Parameter	Required	Type	Description
market_id	true	number	ID of the market
depth	false	number	The number of entries to return for bids and asks. If `depth` has an invalid value (i.e. `0, -1, 1.5`) all bids and asks will be returned

Notification

Name	Type	Description
subscription	string	ID of the subscription
result	object
› data	object
› › price_nodes	object
› › › asks	array of [string, string]	Array of `[price, quantity]` tuples
› › › bids	array of [string, string]	See "asks" field
› › ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› meta	object
› › channel	string	Channel name

`bookL3|{market_id}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "price_nodes": {
                    "asks": [
                        [
                            "2875000000000000000000000",
                            "2664000000000000000000000000"
                        ],
                        [
                            "2886000000000000000000000",
                            "1665000000000000000000000000"
                        ]
                    ],
                    "bids": [
                        [
                            "2868000000000000000000000",
                            "2281710000000000000000000000"
                        ],
                        [
                            "2858000000000000000000000",
                            "4980000000000000000000000"
                        ]
                    ]
                },
                "ts": "1667904821218813009"
            },
            "meta": {
                "channel": "bookL3|1"
            }
        },
        "subscription": "c1d8ffcc-fc4f-4da2-ba8c-ccb6e511c761"
    }
}

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "market_id": 1,
                "price_node_changes": [
                    {
                        "price": "2865000000000000000000000",
                        "quantity": "26730000000000000000000000",
                        "side": "bid"
                    }
                ],
                "ts": "1667904960555004021"
            },
            "meta": {
                "channel": "bookL3|1"
            }
        },
        "subscription": "c1d8ffcc-fc4f-4da2-ba8c-ccb6e511c761"
    }
}

Subscribe to the orderbook L3 data. In response you receive an initial snapshot of the orderbook. Each next notification means absolutely quantity for a given price level changes. If quantity is 0, it means there are no orders for a given price level.

Channel Parameters

Parameter	Required	Type	Description
market_id	true	number	ID of the market

Response

Name	Type	Description
subscription	string	ID of the subscription
result	object
› data	object
› › price_nodes	object
› › › asks	array of [string, string]	Array of [price, quantity] tuples
› › › bids	array of [string, string]	See "asks" field
› › ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› meta	object
› › channel	string	Channel name

Notification

Name	Type	Description
subscription	string
result	object
› data	object
› › market_id	number	ID of the market
› › price_node_changes	object
› › › price	string	Level price inside orderbook
› › › quantity	quantity	Absolutely quantity for a given price level
› › › side	string	`bid` or `ask`
› › ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› meta	object
› › channel	string	Channel name

`account|trades|{account_id}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "block_number": 78000234,
                "maker_fee": "-1613700000000000000000000",
                "maker_fee_token_id": 2,
                "maker_id": "1.user.testnet",
                "market_id": 1,
                "order_maker_id": "744713",
                "order_taker_id": "744795",
                "price": "2934000000000000000000000",
                "quantity": "1100000000000000000000000000",
                "side": "ask",
                "taker_fee": "3227400000000000000000000",
                "taker_fee_token_id": 2,
                "taker_id": "2.user.testnet",
                "ts": "1667923879820301498"
            },
            "meta": {
                "channel": "account|trades|user.testnet"
            }
        },
        "subscription": "3fe23bac-a678-402e-b61d-50fe12b2e614"
    }
}

Subscribes to the trades stream of a particular account by it's ID.

Channel Parameters

Parameter	Required	Type	Description
account_id	true	string

Notification

Name	Type	Description
subscription	string	ID of the subscription
result	object
› data	object
› › block_number	number	Block number in which the transaction was added
› › maker_fee	string	Comission amount from the maker side. If negative then rebate
› › maker_fee_token_id	number	Token ID in which the maker paid the fee
› › maker_id	string	Near account ID of the maker
› › market_id	number	Market ID
› › order_maker_id	string	Matched order ID from the maker side
› › order_taker_id	string	Matched order ID from the taker side
› › price	string	Matching price in the quote currency
› › quantity	string	Matching quantity in the base currency
› › side	string	`bid` or `ask`
› › taker_fee	string	Comission amount from the taker side
› › taker_fee_token_id	string	Token ID in which the taker paid the fee
› › taker_id	string	Near account id of the taker
› › ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› meta	object
› › channel	string	Channel name

`account|orders|{account_id}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": [
                {
                    "account_id": "user.testnet",
                    "average_price": "0",
                    "block_number": 78000240,
                    "client_order_id": null,
                    "created_at": "1667923887499519147",
                    "market_id": 1,
                    "order_id": "744796",
                    "price": "2907000000000000000000000",
                    "quantity": "2290730000000000000000000000",
                    "remaining": "2290730000000000000000000000",
                    "side": "bid",
                    "status": "new",
                    "txn_hash": "BWAnUchxv1coRYXRMoxZ2vsPXvg9jiBXcjRcrxXE4UZE",
                    "updated_at": "1667923887499519147"
                },
                {
                    "account_id": "user.testnet",
                    "average_price": "0",
                    "block_number": 78000240,
                    "client_order_id": null,
                    "created_at": "1667923887499519147",
                    "market_id": 1,
                    "order_id": "744797",
                    "price": "2896000000000000000000000",
                    "quantity": "1437140000000000000000000000",
                    "remaining": "1437140000000000000000000000",
                    "side": "bid",
                    "status": "new",
                    "txn_hash": "BWAnUchxv1coRYXRMoxZ2vsPXvg9jiBXcjRcrxXE4UZE",
                    "updated_at": "1667923887499519147"
                }
            ],
            "meta": {
                "channel": "account|orders|user.testnet"
            }
        },
        "subscription": "41974e41-a720-4e17-8ff9-06ac3c3b7802"
    }
}

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "account_id": "user.testnet",
                "average_price": "0",
                "block_number": 78000288,
                "client_order_id": null,
                "market_id": 1,
                "order_id": "744817",
                "price": "2943000000000000000000000",
                "quantity": "1901920000000000000000000000",
                "remaining": "1901920000000000000000000000",
                "side": "ask",
                "status": "new",
                "ts": "1667923951503435633",
                "txn_hash": "4H6HQS1g2U4Sxd8U94fwpD38mEBMvuV1rBEuFZnmBsMM"
            },
            "meta": {
                "channel": "account|orders|user.testnet"
            }
        },
        "subscription": "41974e41-a720-4e17-8ff9-06ac3c3b7802"
    }
}

Subscribes to the all orders stream of a particular account by it's ID.

Channel Parameters

Parameter	Required	Type	Description
account_id	true	string

Response

Name	Type	Description
subscription	string
result	object
› data	array of object
› › account_id	string	Order owner near account ID
› › average_price	string	Average price of the order match. `0` if the order hasn't yet been filled at all
› › block_number	number	Block number in which the transaction was added
› › client_order_id	string	Custom order ID. Optionally set by the user when order placing
› › market_id	number	Market ID
› › order_id	string	Order ID. Set by contract. Unique identificator among all orders
› › price	string	Limit price of the order in the quote currency
› › quantity	string	Initial quantity of the order in base currency
› › remaining	string	Remaining order quantity to be executed in base currency
› › side	string	`bid` or `ask`
› › status	string	`new`, `filled`, `partially_filled`, `cancelled`
› › created_at	string	Order creation timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› › updated_at	string	Last order update timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› › txn_hash	string	Transaction hash
› meta	object
› › channel	string	Channel name

Notification

Name	Type	Description
subscription	string
result	object
› data	object
› › account_id	string
› › average_price	string
› › block_number	number
› › client_order_id	string
› › market_id	number
› › order_id	string
› › price	string
› › quantity	string
› › remaining	string
› › side	string	`bid` or `ask`
› › status	string	`new`, `filled`, `partially_filled`, `cancelled`
› › ts	string	Order update timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› › txn_hash	string
› meta	object
› › channel	string	Channel name

`account|balances|{account_id}`

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": [
                {
                    "available": "2803065000000000000000000",
                    "reserved": "3567050000000000000000000000",
                    "token_id": 1
                },
                {
                    "available": "3794257181000000000000000000",
                    "reserved": "12486140330000000000000000000",
                    "token_id": 2
                }
            ],
            "meta": {
                "channel": "account|balances|user.testnet"
            }
        },
        "subscription": "58380487-63b5-4bdb-a573-685a808e242e"
    }
}

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "result": {
            "data": {
                "account_id": "user.testnet",
                "action": "buy",
                "quantity": "5540400000000000000000000000",
                "token_id": 2
            },
            "meta": {
                "channel": "account|balances|user.testnet"
            }
        },
        "subscription": "58380487-63b5-4bdb-a573-685a808e242e"
    }
}

Subscribes to the balance changes stream of a particular account by it's ID.

Channel Parameters

Parameter	Required	Type	Description
account_id	true	string

Response

Name	Type	Description
subscription	string
result	object
› data	array of object
› › available	string	Available balance to trade
› › reserved	string	Locked balance in open orders
› › token_id	number	Token ID
› meta	object
› › channel	string	Channel name

Notification

Name	Type	Description
subscription	string
result	object
› data	object
› › account_id	string
› › action	string	`withdraw`, `deposit`, `reserve`, `release`, `buy`, `sell`
› › quantity	string
› › token_id	number
› meta	object
› › channel	string	Channel name

Methods

`ping`

{
    "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": 78016624,
            "id": 10000000000135505,
            "maker_fee": "-761000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751404",
            "order_taker_id": "751450",
            "price": "2626000000000000000000000",
            "quantity": "580000000000000000000000",
            "side": "ask",
            "taker_fee": "1523000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943987855748256"
        },
        {
            "block_number": 78016512,
            "id": 10000000000135504,
            "maker_fee": "-147226000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751404",
            "order_taker_id": "751448",
            "price": "2626000000000000000000000",
            "quantity": "112130000000000000000000000",
            "side": "ask",
            "taker_fee": "294453000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943852292365268"
        },
        {
            "block_number": 78016467,
            "id": 10000000000135503,
            "maker_fee": "-1055000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751409",
            "order_taker_id": "751447",
            "price": "2633000000000000000000000",
            "quantity": "2110000000000000000000000",
            "side": "bid",
            "taker_fee": "2110000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943801961525287"
        }
    ],
    "id": 0
}

Returns the latest trades that have occurred for 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": 78016624,
            "id": 10000000000135505,
            "maker_fee": "-761000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751404",
            "order_taker_id": "751450",
            "price": "2626000000000000000000000",
            "quantity": "580000000000000000000000",
            "side": "ask",
            "taker_fee": "1523000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943987855748256"
        },
        {
            "block_number": 78016512,
            "id": 10000000000135504,
            "maker_fee": "-147226000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751404",
            "order_taker_id": "751448",
            "price": "2626000000000000000000000",
            "quantity": "112130000000000000000000000",
            "side": "ask",
            "taker_fee": "294453000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943852292365268"
        },
        {
            "block_number": 78016467,
            "id": 10000000000135503,
            "maker_fee": "-1055000000000000000000",
            "maker_fee_token_id": 1,
            "maker_id": "1.user.testnet",
            "market_id": 1,
            "order_maker_id": "751409",
            "order_taker_id": "751447",
            "price": "2633000000000000000000000",
            "quantity": "2110000000000000000000000",
            "side": "bid",
            "taker_fee": "2110000000000000000000",
            "taker_fee_token_id": 1,
            "taker_id": "2.user.testnet",
            "ts": "1667943801961525287"
        }
    ],
    "id": 0
}

Returns the latest trades that have occurred for a specific account ID (including either taker or maker).

Parameters

#	Type	Description
0.	string	Account ID
1.	number	Limit
2.	number	Offset

Response

Name	Type	Description
result	array of objects
› id	number	Unique ID of the trade among specified market
› block_number	number	Block number in which the transaction was added
› maker_fee	string	Comission amount from the maker side. If negative then rebate
› maker_fee_token_id	number	number
› maker_id	string	Near account ID of the maker
› market_id	number	Market ID
› order_maker_id	string	Matched order ID from the maker side
› order_taker_id	string	Matched order ID from the taker side
› price	string	Matching price in the quote currency
› quantity	string	Matching quantity in the base currency
› side	string	`bid` or `ask`
› taker_fee	string	Comission amount from the taker side
› taker_fee_token_id	string	Token ID in which the taker paid the fee
› taker_id	string	Near account ID of the taker
› ts	string	Timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)

`get_orders_history`

{
    "jsonrpc": "2.0",
    "result": [
        {
            "account_id": "user.testnet",
            "average_price": "10000",
            "block_number": 86373460,
            "client_order_id": "",
            "created_at": "1649164215000000000",
            "market_id": 1,
            "order_id": "5",
            "price": "10000",
            "quantity": "10000000000000000000000",
            "remaining": "0",
            "side": "ask",
            "status": "filled",
            "txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
            "updated_at": "1649164215000000000"
        },
        {
            "account_id": "user.testnet",
            "average_price": "20000",
            "block_number": 86373460,
            "client_order_id": "",
            "created_at": "1649164215000000000",
            "market_id": 1,
            "order_id": "6",
            "price": "20000",
            "quantity": "10000000000000000000000",
            "remaining": "0",
            "side": "ask",
            "status": "filled",
            "txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
            "updated_at": "1649164215000000000"
        },
        {
            "account_id": "user.testnet",
            "average_price": "20000",
            "block_number": 86373460,
            "client_order_id": "",
            "created_at": "1649164215000000000",
            "market_id": 1,
            "order_id": "7",
            "price": "20000",
            "quantity": "20000000000000000000000",
            "remaining": "0",
            "side": "bid",
            "status": "filled",
            "txn_hash": "E2DVfDMfUhP3WypFXoWWjM4CRN448gVnQC8hXEtiTMoo",
            "updated_at": "1649164215000000000"
        }
    ],
    "id": 0
}

Returns history of orders that have been partially or fully filled or cancelled.

Parameters

#	Type	Description
0.	number	Market ID
1.	string	Account ID
2.	number	Limit
3.	number	Offset

Response

Name	Type	Description
result	array of objects
› account_id	string	Order owner near account ID
› average_price	string	Average price of the order match. `0` if the order hasn't yet been filled at all
› block_number	number	Block number in which the transaction was added
› client_order_id	string	Custom order ID. Optionally set by the user when order placing
› market_id	number	Market ID
› order_id	string	Order ID. Set by contract. Unique identificator among all orders
› price	string	Limit price of the order in the quote currency
› quantity	string	Initial quantity of the order in base currency
› remaining	string	Remaining order quantity to be executed in base currency
› side	string	`bid` or `ask`
› status	string	`new`, `filled`, `partially_filled`, `cancelled`
› created_at	string	Order creation timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› updated_at	string	Last order update timestamp in nanoseconds (`1 second = 1 * 10^9 nanosecond`)
› txn_hash	string	string

`get_candles`

{
    "jsonrpc": "2.0",
    "result": [
        {
            "base_volume": "19620000000000000000000000",
            "close": "3139000000000000000000000",
            "close_ts": "1667264400000000000",
            "high": "3139000000000000000000000",
            "low": "3102000000000000000000000",
            "open": "3128000000000000000000000",
            "open_ts": "1667260800000000000",
            "quote_volume": "61255590000000000000000000"
        },
        {
            "base_volume": "73000000000000000000000000",
            "close": "3135000000000000000000000",
            "close_ts": "1667268000000000000",
            "high": "3135000000000000000000000",
            "low": "3120000000000000000000000",
            "open": "3120000000000000000000000",
            "open_ts": "1667264400000000000",
            "quote_volume": "227860050000000000000000000"
        }
    ],
    "id": 0
}

Returns history of candles to use in OHLC chart.

Parameters

#	Type	Enum	Description
0.	number		Market ID
1.	number	`1`, `3`, `5`, `10`, `15`, `30`, `60`, `120`, `180`, `240`, `480`, `720`, `1440`	Interval in minutes
2.	number		From (timestamp in nanoseconds)
3.	number		To (timestamp in nanoseconds)
4.	number		Limit
5.	number		Offset

Response

Name	Type	Description
result	array of objects
› high	string	Highest price for the specified interval
› low	string	Lowest price for the specified interval
› open	string	Open price for the specified interval
› close	string	Close price for the specified interval
› quote_volume	string	Total volume in quote currencies for the specified
› base_volume	string	Total volume in base currencies for the specified
› open_ts	string	Open timestamp of the specified interval in nanoseconds (inclusive)
› close_ts	string	Close timestamp of the specified interval in nanoseconds (exclusive)

Errors

Contract errors

Error String	Meaning
Market not found.	Incorrect `market_id`.
Order not found.	Incorrect `order_id`.
Placing operations suspended.	Market is stopped and placing orders is unavailable.
Cancellation operations suspended.	Market is stopped and cancelling orders is unavailable.
Self-trading is prohibited	Placing order is trying to match with the limit order from the same account.
Insufficient funds to complete the transaction.	Self-explanatory, could be due to incorrect number of zeros in price or quantity parameter.
Expected positive amount. User: {}, token: {}, amount: {}	Incorrect parameter usually while deposit or withdraw.
Expected prepaid gas.	Insuficient amount of gas.
Order price precision should be greater than tick size.	Incorrect order price precision.
Order quantity precision should be greater than step size.	Incorrect order quantity precision.
Base asset quantity is less than minimum.	Order quantity is too low.
Base asset quantity is greater than maximum.	Order quantity is too high.
Quote asset quantity is less than minimum.	Order notional size (`price*quantity`) is too low.
Quote asset quantity is greater than maximum.	Order notional size (`price*quantity`) is too high.

Gateway errors

Coming soon!

Events

/// Spot events.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub enum Event {
    /// Orderbook node update event.
    Orderbook {
        /// Market id.
        market_id: u16,
        /// Price.
        price: u128,
        /// Quantity.
        quantity: u128,
        /// Order side.
        side: OrderSide,
    },

    /// Order update event.
    Order {
        /// Market id.
        market_id: u16,
        /// Order id.
        order_id: u128,
        /// User id.
        user_id: String,
        /// Price.
        price: u128,
        /// Average price
        average_price: u128,
        /// Quantity.
        quantity: u128,
        /// Remaining quantity.
        remaining: u128,
        /// Order side.
        side: OrderSide,
        /// Order status.
        status: OrderStatus,
        /// Client order identifier.
        client_order_id: Option<u32>,
    },

    /// Trade update event.
    Trade {
        /// Market id.
        market_id: u16,
        /// Maker order identifier.
        maker_order_id: u128,
        /// Taker order identifier.
        taker_order_id: u128,
        /// Maker fee amount.
        maker_fee: u128,
        /// Maker fee token.
        maker_fee_token_id: u16,
        /// Taker fee amount.
        taker_fee: u128,
        /// Taker fee token.
        taker_fee_token_id: u16,
        /// Is rebate for maker.
        is_maker_fee_rebate: bool,
        /// Price.
        price: u128,
        /// Quantity.
        quantity: u128,
        /// Order side.
        side: OrderSide,
    },

    /// Balance update event.
    Balance {
        /// User id.
        user_id: AccountId,
        /// Token id.
        token_id: u16,
        /// Amount.
        amount: u128,
        /// Is income or outcome.
        increased: bool,
        /// Type of change.
        change_type: BalanceChangeInfo,
    },
}

/// Balance change event.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub enum BalanceChangeInfo {
    /// External change - deposit or withdraw.
    External,
    /// Reserving balance for a limit order.
    Locked(u128),
    /// Executing order.
    Trade(u128),
}

/// Order type.
#[derive(BorshSerialize, BorshDeserialize, Debug, Clone, Copy, Ord, PartialOrd, Eq, PartialEq, Deserialize, Serialize, Hash)]
pub enum OrderSide {
    /// Ask(sell) order.
    Ask,
    /// Bid(buy) order.
    Bid,
}

/// Order status.
#[derive(BorshSerialize, BorshDeserialize, Serialize, Deserialize, Ord, PartialOrd, Eq, PartialEq, Debug, Clone)]
pub enum OrderStatus {
    /// New.
    New,
    /// Cancelled.
    Cancelled,
    /// Filled.
    Filled,
    /// Partially filled.
    PartiallyFilled,
    /// Match orders count limit reached.
    LimitReached,
}

/// Account id.
pub type AccountId = String;

/// Contract log.
#[derive(BorshSerialize, BorshDeserialize, Clone, Eq, PartialEq, Debug, Serialize)]
pub struct EventWithMeta {
    /// Event.
    pub data: Event,
    /// Identifier.
    pub id: u64,
}

To be informed about some changes inside DEX we use standart way for NEAR Protocol - events.

Example

Assume you have that log string AwAAAAABAACCFAAAAAAAAAAAAAAAAAAAAMBB2Sz5k9cM7gEAAAAAARdRgAAAAAAAA0AAAAA1MDE4YWYyZjhkNWUzZjYzOWM2ZmU1NDZhMWQ5YTRlNjJjNjk5NTM5Yjg5MTc5NmIxNWRkNGMxMDM5ZGE2NWQxAgCAvEMWAAAAAAAAAAAAAAAAAAFL6BIAAAAAAAAAAAAAAAAAGFGAAAAAAAABAQBL6BIAAAAAAAAAAAAAAAAAQAAAADUwMThhZjJmOGQ1ZTNmNjM5YzZmZTU0NmExZDlhNGU2MmM2OTk1MzliODkxNzk2YjE1ZGQ0YzEwMzlkYTY1ZDEAghQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQPbxBW199+XlAAAAAAAAAED28QVtfffl5QAAAAAAAQAAGVGAAAAAAAA=.

To make it more readable you need to decode it using base64 format and need to deserialize result using events scheme. The result will be presented as Vec<EventWithMeta>.