Build a market maker

A market maker on hexbook is a handful of contract calls and signed intents. This page shows how they fit together, so you can build one in any language.

The loop

One cycle, repeated: take a reference price, compute the ladder, compare it with your live orders, send the difference as one atomic batch. What you build:

Part	Responsibility	hexbook primitive
Reference price	a fair price you trust, two-sided if possible	none: your choice of venue or oracle
Quoting	spread, levels, sizes, inventory skew	raw prices, tick size, minimum
Executor	turns a desired ladder into one transaction	`batch`, `cancel_all`
Signer	signs intents with your key	NEP-413 `auth_call`
State reader	your live orders and balances	views
Fill tracker	what traded, at what price	events, sources
Safety	TTL, kill switch, limits	Risk

1. Account and key

Use a dedicated account. An implicit account (the hex of an ed25519 public key) works with intents.near as is; a named account first registers its key with intents.near add_public_key.
One key signs every intent. Keep it out of code and config files.
Submitting through the solver relay needs a NEAR Intents API key; submitting through your own transactions needs NEAR for gas (reserve).

2. Prices and amounts

The contract works in raw units. Convert with integer or decimal arithmetic, never floats:

// Moves the decimal point of a decimal string by `shift` places (positive: right), no floats.
function shiftDecimal(value: string, shift: number): string {
  const [int, frac = ""] = value.split(".");
  let digits = int + frac;
  let point = int.length + shift; // position of the decimal point in `digits`
  if (point <= 0) { digits = "0".repeat(1 - point) + digits; point = 1; }
  if (point > digits.length) digits += "0".repeat(point - digits.length);
  const head = digits.slice(0, point).replace(/^0+(?=\d)/, "");
  const tail = digits.slice(point).replace(/0+$/, "");
  return tail ? `${head}.${tail}` : head;
}

// raw price = quote raw units per 1 base raw unit
// human 138.4 USDT/QTC, QTC 12 decimals, USDT 6 decimals -> "0.0001384"
const toRawPrice = (human: string, baseDecimals: number, quoteDecimals: number) =>
  shiftDecimal(human, quoteDecimals - baseDecimals);

Round to the book’s tick_size away from the market: bids down, asks up.

// p and tick as scaled integers of the raw price (same number of fractional digits for both)
const roundBid = (p: bigint, tick: bigint) => (tick === 0n ? p : (p / tick) * tick);
const roundAsk = (p: bigint, tick: bigint) => (tick === 0n ? p : ((p + tick - 1n) / tick) * tick);

Sizes: an ask’s amount is base, a bid’s is quote (price × the base you want to buy). Each must be at least the book’s min_order_amount for its side (get_active_pairs).

3. Funding

Your tokens must first be in your intents.near balance: deposit them into NEAR Intents (see Deposits in the NEAR Intents docs). Then move inventory from intents.near into the book’s internal balance once, with a deposit per token:

{
  "intent": "transfer",
  "receiver_id": "hexbook.near",
  "tokens": { "nep141:usdt.tether-token.near": "500000000" },
  "msg": "{\"deposit\":true}"
}

Then set payout mode internal, so fills come back to the same balance and back new orders without another deposit.

4. Quoting with batch

Keep the ladder you want as a list of { side, price, amount } (prices already on the tick, amounts above the minimum, at most one order per side and price) and compare it with your orders in the book. Read them with get_orders_by_owner, which returns dead orders too, and get_order_meta for liveness and expiry:

type Side = "sell" | "buy";
type Desired = { side: Side; price: string; amount: bigint };
type Mine = { hash: string; side: Side; price: string; amount: bigint; expiresAt: bigint };
// `view(method, args)` is your NEAR RPC call_function wrapper (see Views). Parse its JSON keeping u64 values exact,
// or accept that `expires_at` (above 2^53) loses a few hundred ns: harmless for the comparison below.
declare function view(method: string, args: object): Promise<any>;

// Views return prices normalized ("0.0001390" comes back "0.000139"): compare them as numbers.
const UD128_DECIMALS = 38;
const priceKey = (p: string) => {
  const [int, frac = ""] = p.split(".");
  return BigInt(int + frac.padEnd(UD128_DECIMALS, "0"));
};
const key = (o: { side: Side; price: string; amount: bigint }) => `${o.side}:${priceKey(o.price)}:${o.amount}`;

async function readMine(token_pair: object, owner_id: string) {
  const live: Mine[] = [];
  const dead: string[] = [];
  for (let skip = 0; ; skip += 100) {
    const page = await view("get_orders_by_owner", { token_pair, owner_id, skip, limit: 100 });
    for (const o of page) {
      const meta = await view("get_order_meta", { token_pair, hash: o.hash });
      if (!meta) continue; // closed since the page was read
      if (!meta.live) dead.push(o.hash); // expired or stale epoch: still holds a slot
      // order_balance is what is left after partial fills
      else live.push({ hash: o.hash, side: o.order.side, price: o.order.price,
                       amount: BigInt(o.order_balance), expiresAt: BigInt(meta.expires_at) });
    }
    if (page.length < 100) break;
  }
  return { live, dead };
}

// nowNs, tickNs, ttlNs: bigint nanoseconds
function diff(desired: Desired[], live: Mine[], dead: string[], nowNs: bigint, tickNs: bigint, ttlNs: bigint) {
  const wanted = new Set(desired.map(key));
  const kept = new Set<string>();
  const cancel = [...dead]; // close your dead orders with the requote
  for (const o of live) {
    const k = key(o);
    // keep an unchanged order unless it expires before the next tick
    const fresh = o.expiresAt === 0n || o.expiresAt > nowNs + tickNs;
    if (wanted.has(k) && fresh && !kept.has(k)) kept.add(k);
    else cancel.push(o.hash);
  }
  const place = desired
    .filter((o) => !kept.has(key(o)))
    .map((o) => ({ side: o.side, price: o.price, amount: o.amount.toString(), expires_at: (nowNs + ttlNs).toString() }));
  // at most 64 cancels and 32 places per batch: the rest goes in the next tick
  return { cancel: cancel.slice(0, 64), place: place.slice(0, 32) };
}

const { live, dead } = await readMine(token_pair, me);
const { cancel, place } = diff(desired, live, dead, nowNs, tickNs, ttlNs);
if (cancel.length || place.length) await sendBatch({ token_pair, cancel, place }); // your signer + submitter

One batch per tick: the whole requote lands or none of it. Wait for its outcome (the hexbook.near receipt’s order_created and place_skipped) before the next one.
Requote only when it matters (the fair moved more than a fraction of your half-spread, or a level filled): an unchanged order keeps its time priority.
Every order carries expires_at, a few tick intervals out: if your process stops, the ladder dies on its own. Re-place orders that expire within about a tick.
Close your dead orders. Expired and stale-epoch orders still count toward the 200-per-owner and 500-per-level limits and the 128-order live-price scan. List them in the same batch’s cancel (it accepts dead orders), as above; prune is a fallback. A hash that was closed meanwhile (a trade met it, someone pruned it) makes the batch panic: read your orders right before building it.
Replace everything with bump_epoch: true, the old hashes in cancel and the full ladder in place.
amount and price are JSON strings.

The batch is an auth_call with msg {"action":"batch","data":{...}}, signed with NEP-413.

5. Reading your state

You need	Call
your orders, live and dead	`get_orders_by_owner` (side, price, remaining `order_balance`) + `get_order_meta` (`live`, `expires_at`)
the live book	`get_orderbook` with `with_extra: true` (live only, `owner` per order)
your free inventory	`get_user_balance({ account_id })`
the book config	`get_book_config({ token_pair })`: fees, minimum, tick size
what a taker would get	`get_quote_pub(...)`

6. Tracking fills

Use both:

Diff your state between ticks. An order that is gone or smaller was filled or closed; with payout mode internal your internal balance moved by the proceeds.
Read the events. trade lists every maker fill (f) and closed order (c); place_skipped tells you a placement did not rest.

7. Lifecycle

The whole life of a market maker, in order:

Account and key

A dedicated account whose key intents.near knows (1).

Fund

Deposit the tokens into NEAR Intents, then deposit each into the book’s internal balance (3).

Payout mode

set_payout_mode internal, so fills come back into the balance your batches spend.

Post the ladder

batch with bump_epoch: true, your old hashes (if any) in cancel and up to 32 placements with a short expires_at.

Requote

Each tick: read your orders, diff, one batch with the stale, expiring and dead hashes in cancel and the new placements; wait for its outcome (4).

Kill switch

cancel_all (or a batch with bump_epoch: true and no places) when the reference is stale or jumps, or a limit trips (Risk). Then cancel the now-dead hashes in your next batch.

Limits

Cap what you hold per asset and stop quoting the side that would grow past it.

Exit

cancel_all, a batch cancelling every remaining hash (or prune), then claim_balance (every token in one call) or withdraw per token.

Details in Risk.

Overview

Contract

Market making

Indexing

The loop

1. Account and key

2. Prices and amounts

3. Funding

4. Quoting with batch

5. Reading your state

6. Tracking fills

7. Lifecycle

​The loop

​1. Account and key

​2. Prices and amounts

​3. Funding

​4. Quoting with batch

​5. Reading your state

​6. Tracking fills

​7. Lifecycle

The loop

1. Account and key

2. Prices and amounts

3. Funding

4. Quoting with batch

5. Reading your state

6. Tracking fills

7. Lifecycle