Skip to main content

API Reference (v1 spot)

Setup

Prerequisites

Create a NEAR testnet wallet and install the NEAR CLI. Make sure you can interact with testnet.

near login

CLI

You can experiment with Tonic using the CLI.

npm i -g @tonic-foundation/cli
tonic --help

TypeScript

Yarn

yarn add near-api-js @tonic-foundation/tonic @tonic-foundation/utils

NPM

npm install near-api-js @tonic-foundation/tonic @tonic-foundation/utils

Reference Documentation

tip: testnet faucets

We've deployed a few test token contracts, some of which are used in the examples below. Mint some from the testnet faucet if you want to follow along, and feel free to use them in your own experiments.

Mint commands (our testnet tokens don't require a storage deposit)

Mint 1000 "USDC"

near call fake-usdc.testnet ft_mint \
'{"account_id": "your-account.testnet", "amount": "1000000000"}' \
--accountId your-account.testnet

Mint 10 "wBTC"

near call fake-btc.testnet ft_mint \
'{"account_id": "your-account.testnet", "amount": "1000000000"}' \
--accountId your-account.testnet

Connect

The Tonic CLI is configured the same way as the NEAR CLI. See the NEAR CLI repo for detailed information. TL;DR - if you've logged into an account with the NEAR CLI, you can use that account with the Tonic CLI.

near login
Further Reading
NEAR's account model may be different than other blockchains you are familiar with. To learn more about top level accounts, subaccounts, and access keys see the [NEAR documentation](https://docs.near.org/docs/concepts/account).

List markets

Get a paginated list of all markets from the chain.

tonic list-markets
tonic list-markets --offset 100 --limit 100

List markets (data API)

Get a list of all markets supported by market making partners from the data API.

curl https://data-api.testnet.tonic.foundation/api/v1/markets?quoteToken=WBTC&baseToken=USDC

Get information about a market

Get data about a market, including its token pair, orderbook, and fees.

tonic get-market $MARKET_ID

Get orderbook and prices

tonic get-open-orders 1434171647166217159

Create an account

NEAR uses storage staking to cover the cost of on-chain storage. You must stake NEAR with the contract in order to place orders and hold balances.

tonic storage-deposit 0.1 --accountId your-account.testnet

You can deposit on behalf of other accounts as well.

tonic storage-deposit 0.1 other-account.testnet --accountId your-account.testnet

Deposit funds

Deposit funds into the DEX to begin trading.

# deposit 1000 "USDC"
tonic deposit fake-usdc.testnet 1000 --accountId your-account.testnet

# despoit 10 NEAR
tonic deposit near 10 --accountId your-account.testnet

Withdraw funds

# withdraw 100 "USDC"
tonic withdraw fake-usdc.testnet 100 --accountId your-account.testnet

# withdraw all "USDC"
tonic withdraw fake-usdc.testnet all --accountId your-account.testnet

# withdraw 10 NEAR
tonic withdraw near 10 --accountId your-account.testnet

# withdraw 10 NEAR to another account
tonic withdraw near 10 other-account.testnet --accountId your-account.testnet

Place an order

Place a limit buy for 1 NEAR @ 10 USDC.

tonic place-order $NEAR_USDC_MARKET_ID --buy --type limit --price 10 --quantity 1
tonic place-order $NEAR_USDC_MARKET_ID --buy --type market --quantity 1

Cancel an order

tonic cancel-order $MARKET_ID $ORDER_ID --accountId your-account.testnet

Cancel all orders

tonic cancel-all-orders $MARKET_ID --accountId your-account.testnet

List all orders

tonic get-open-orders $MARKET_ID --accountId your-account.testnet

Execute batch actions

You can execute batch actions in a single market with a high-level API.

batch-single.ts
import { Tonic } from '@tonic-foundation/tonic';

/**
* Atomically cancel all orders in a market and place a new limit buy.
*/
export async function batchSingle(tonic: Tonic) {
const market = await tonic.getMarket('example-market');
const batch = market.createBatchAction();
batch
.cancelAllOrders()
.newOrder({
side: 'Buy',
orderType: 'Limit',
maxQuantity: 10,
limitPrice: 100,
});
return await tonic.executeBatch(batch);
}

Create a market

Alt heading: list your token on Tonic

Tonic supports spot trading with native NEAR and NEP-141 fungible tokens.

Terminology

In the following sections, we'll often refer to base tokens, quote tokens, and lot sizes.

Base and quote tokens refer to the same concepts as in forex. For example, in the wBTC/USDC market, wBTC is the base token, and USDC is the quote token.

Assets trade on Tonic in fixed size lots. Practically speaking, the base lot size is the smallest increment in order size that you can make when placing an order, and the quote lot size is the smallest price tick. For example, the test USDC token has 6 decimals. To use it as a quote currency in a market with a minimum price tick of 0.01 USDC, we'd need to set the quote lot size to 10000.

NOTE: token accounts

The DEX account must have a storage deposit with every token it lists. This is only required the first time a new token is listed on the DEX.

near call ${TOKEN_CONTRACT} storage_deposit \
'{"account_id": "v1.orderbook.testnet", "registration_only": true}' \
--deposit 0.1 \
--accountId your-account.testnet

Create a market between two fungible tokens.

# 3 zeroes in wBTC lot size = 0.00001 wBTC min tick
tonic create-market \
--base fake-btc.testnet \
--quote fake-usdc.testnet \
--baseLotSize 1000 \
--quoteLotSize 10000 \
--accountId your-account.testnet

Create a market between a fungible token and native NEAR.

# 20 zeroes in NEAR lot size = 0.0001 NEAR tick
tonic create-market \
--base near \
--quote fake-usdc.testnet \
--baseLotSize 100000000000000000000 \
--quoteLotSize 10000 \
--accountId your-account.testnet