Build on routr.

Overview

routr is one NEAR contract that holds two registries: platforms (a launchpad, a wallet, any front end that opens markets) and pools, one per token, quote and platform. A pool is a constant-product market with a virtual quote reserve: the token side is seeded once, there are no LP shares and no liquidity withdrawal, and the quote side starts from a virtual reserve that, with the seed, sets the opening price. Swaps are a single ft_transfer_call. Fees are booked per account at swap time and paid out by anyone.

Concepts

Platform

A registered id (for example fastr) with an owner, a fee recipient, a creator_bps and a builder_bps. Registration is open to anyone and costs the record's storage plus a 0.5 NEAR bond that becomes the platform's storage credit. A platform can name up to 8 pool_creators (usually its factory) so nobody else opens pools under its id, and up to 32 approved builders it pays for routing orders.

Pool key

Every pool has a lookup key token|quote|platform_id that is known before the pool exists, so a token contract can embed its own route at creation. Methods that take a pool_id accept the numeric id or the key.

Curve

Price follows x · (y_real + y_virtual) = k. The seed amount and virtual_quote set the opening price (virtual_quote / seed). Sales pay out of the real quote reserve only, never the virtual one. If tokens exist outside the pool that were not bought from it, selling them can take the price below the opening price. A buy that would push the quote reserve past a fixed bound is refused, which bounds the arithmetic on that path.

Frozen terms

At create_pool the pool copies the protocol share, the protocol recipient, the platform recipient, creator_bps and builder_bps; the caller sets fee_bps. Later changes to the platform or the protocol apply to new pools only. The creator can hand its entitlement to another account, and the platform's list of approved builders applies to all its pools at once.

Quickstart

A launchpad's full path with near-api-js: register once, then per launch create the pool, seed it, quote and route a trade, and claim fees. One script runs on either network; NETWORK picks the routr account, wNEAR and the RPC. Before you run it:

• routr needs a storage deposit on your token: call storage_deposit on the token for the routr account. Tokens that register their venues at creation, as fastr's do, need nothing. routr is already registered on mainnet wNEAR and USDC.
• SEED is the amount of your token the script puts into the pool, in raw units; replace the example value with yours. A seed is final: there is no way to take it back out.
• The example buy spends BUY wNEAR (default 1). Your account must hold that much wNEAR: call near_deposit on the wNEAR contract to wrap NEAR.

Mainnet

npm i near-api-js tsx
NETWORK=mainnet PLATFORM=mypad ACCOUNT=mypad.near TOKEN=mytoken.mypad.near SEED=1000000000000000000000000000 npx tsx quickstart.ts

On mainnet the script spends real funds. Registering a platform attaches 0.52 NEAR, about $2.76 at $5.30 per NEAR on 2026-09-30: the 0.5 NEAR bond is kept as the platform's storage credit and is not refunded, and whatever the record's storage does not use of the rest comes back. Each pool attaches the create_pool_deposit that get_launch_status quotes; the unused part is refunded. Then it seeds SEED of your token for good and buys with BUY wNEAR, paying the pool fee (1% in the example) and any price impact. Platform ids are first come, first served and a platform cannot be deleted, so run the same script on testnet first. The signing key is read from ~/.near-credentials/mainnet/.

Testnet

NETWORK=testnet PLATFORM=mypad ACCOUNT=mypad.testnet TOKEN=mytoken.mypad.testnet SEED=1000000000000000000000000000 npx tsx quickstart.ts

Testnet NEAR is free from the NEAR faucet. routr-dev.testnet runs development builds, which can be ahead of mainnet and are reset when the stored layout changes. The signing key is read from ~/.near-credentials/testnet/.

The script

/**
 * routr quickstart for a launchpad (NEAR, near-api-js v5): register your platform once, then per launch
 * create the pool, seed it with the token supply, quote and route a first trade, and claim fees.
 *
 *   npm i near-api-js tsx
 *   NETWORK=mainnet PLATFORM=mypad ACCOUNT=mypad.near TOKEN=mytoken.mypad.near SEED=<raw amount> npx tsx quickstart.ts
 *   NETWORK=testnet PLATFORM=mypad ACCOUNT=mypad.testnet TOKEN=mytoken.mypad.testnet SEED=<raw amount> npx tsx quickstart.ts
 *
 * NETWORK picks routr's account, wNEAR and the RPC (mainnet: routr.near, wrap.near; testnet: routr-dev.testnet,
 * wrap.testnet). routr must hold a storage deposit on TOKEN before the seed (storage_deposit on the token for the
 * routr account); it already has one on wNEAR and native USDC on mainnet.
 *
 * On mainnet this spends real funds: the 0.5 NEAR platform bond (kept as storage credit, not refunded), the pool's
 * storage deposit, the SEED of your token (final: a seed cannot be withdrawn) and BUY wNEAR (default 1) for the
 * example buy, which ACCOUNT must already hold (near_deposit on wrap.near wraps NEAR). Try it on testnet first.
 *
 * Every call below is one contract method; the contract's own docs are in contracts/routr/src/lib.rs.
 * Amounts are strings of raw units (yocto for wNEAR). Pools are addressable by their key
 * `${token}|${quote}|${platform}` before they exist, so a token can carry its own route.
 */
import { connect, keyStores, Account, utils } from "near-api-js";

const NETWORK = process.env.NETWORK ?? "mainnet";
const NET = ({
  mainnet: { routr: "routr.near", wrap: "wrap.near", rpc: "https://rpc.mainnet.fastnear.com" },
  testnet: { routr: "routr-dev.testnet", wrap: "wrap.testnet", rpc: "https://rpc.testnet.fastnear.com" },
} as Record<string, { routr: string; wrap: string; rpc: string }>)[NETWORK];
if (!NET) throw new Error(`NETWORK must be mainnet or testnet, not ${NETWORK}`);
const ROUTR = process.env.ROUTR ?? NET.routr;
const PLATFORM = process.env.PLATFORM ?? "mypad";
const ACCOUNT = process.env.ACCOUNT!; // your platform's account (its factory/locker seeds pools)
const WRAP = NET.wrap;
const TGAS = (n: number) => BigInt(n) * 10n ** 12n;
const NEAR = (n: string) => utils.format.parseNearAmount(n)!;
const SEED = process.env.SEED; // raw units of TOKEN to seed; required, because a seed is final
const BUY = process.env.BUY ?? "1"; // wNEAR for the example buy

async function main() {
  const near = await connect({
    networkId: NETWORK,
    nodeUrl: NET.rpc,
    keyStore: new keyStores.UnencryptedFileSystemKeyStore(`${process.env.HOME}/.near-credentials`),
  });
  const me = await near.account(ACCOUNT);
  const view = (method: string, args: object) => me.viewFunction({ contractId: ROUTR, methodName: method, args });

  // 1. Register the platform once: 70% of the platform's part to each pool's creator, 5% to approved builders,
  //    only this account may create pools under the id. The 0.5 NEAR bond is the platform's storage credit for
  //    the claim keys its pools' swaps create (top it up any time with `platform_top_up`).
  const existing = await view("get_platform", { platform_id: PLATFORM });
  if (existing && existing.owner !== ACCOUNT) {
    throw new Error(`platform id ${PLATFORM} belongs to ${existing.owner}; pick another id`);
  }
  if (!existing) {
    await me.functionCall({
      contractId: ROUTR, methodName: "register_platform", gas: TGAS(30), attachedDeposit: BigInt(NEAR("0.52")),
      args: { platform_id: PLATFORM, fee_recipient: ACCOUNT, creator_bps: 7000, builder_bps: 500,
              pool_creators: [ACCOUNT], builders: [] },
    });
  }

  // 2. Per launch: check the key, create the pool, seed it. `virtual_quote` sets the starting price:
  //    opening price = virtual_quote / seed; seeding the whole supply with virtual_quote 1,000 NEAR opens the supply's
  //    value at 1,000 NEAR. This is an opening price, not a promise about any later price.
  const token = process.env.TOKEN ?? `mytoken.${ACCOUNT}`; // an NEP-141 whose supply this account holds
  if (!SEED || !/^[0-9]+$/.test(SEED)) throw new Error("set SEED to the raw amount of TOKEN to seed");
  const status = await view("get_launch_status", { token, quote: WRAP, platform_id: PLATFORM });
  console.log("launch status", status.state, "terms", status.terms, "deposit", status.create_pool_deposit);
  if (status.state === "absent") {
    await me.functionCall({
      contractId: ROUTR, methodName: "create_pool", gas: TGAS(30), attachedDeposit: BigInt(status.create_pool_deposit),
      args: { token, quote: WRAP, platform_id: PLATFORM, creator: ACCOUNT, seeder: ACCOUNT, fee_bps: 100,
              virtual_quote: NEAR("1000") },
    });
  }
  if (status.state !== "seeded") {
    // the seed is one ft_transfer_call of the supply; `expect_creator` binds the pool to the fee recipient you expect
    await me.functionCall({
      contractId: token, methodName: "ft_transfer_call", gas: TGAS(60), attachedDeposit: 1n,
      args: { receiver_id: ROUTR, amount: SEED,
              msg: JSON.stringify({ Seed: { pool_id: status.key, expect_creator: ACCOUNT } }) },
    });
  }

  // 3. Quote and route a buy: the quote is what you show before the user signs (fee waterfall, impact, executable).
  const amountIn = NEAR(BUY);
  const q = await view("quote_swap", { pool_id: status.key, token_in: WRAP, amount_in: amountIn, builder: null });
  if (!q) throw new Error(`no pool ${status.key}`);
  console.log("quote", q.amount_out, "impact bps", q.price_impact_bps, "executable", q.executable, q.reason ?? "");
  if (q.executable) {
    const minOut = (BigInt(q.amount_out) * 98n) / 100n; // 2% slippage
    await me.functionCall({
      contractId: WRAP, methodName: "ft_transfer_call", gas: TGAS(100), attachedDeposit: 1n,
      args: { receiver_id: ROUTR, amount: amountIn,
              msg: JSON.stringify({ Swap: { pool_id: status.key, min_out: minOut.toString(), recipient: null, builder: null } }) },
    });
  }

  // 4. Fees: booked per account at swap time; anyone can push them. A contract recipient reconciles with
  //    `get_claim_info` (cumulative creator leg vs cumulative delivered) instead of trusting a single push.
  const info = await view("get_claim_info", { pool_id: status.key, account: ACCOUNT });
  console.log("creator leg", info.fees_creator, "delivered so far", info.delivered);
  await me.functionCall({ contractId: ROUTR, methodName: "push", gas: TGAS(40), args: { account: ACCOUNT, token: WRAP } });

  // 5. Events for your indexer: NEP-297 standard "routr" (pool_created, pool_seeded, swap with every fee leg and
  //    the reserves after, payout). Page your own pools with get_platform_pools(platform_id, from, limit).
  console.log("my pools", await view("get_platform_pools", { platform_id: PLATFORM, from: 0, limit: 20 }));
}

main().catch((e) => { console.error(e); process.exit(1); });

The example registers a platform id only if it is free. If get_platform returns a record, check that its owner, recipient and pool creators are yours before using it.

Messages

Seeding and swapping are NEP-141 transfers to routr with a JSON msg. routr returns the unused amount, so a rejected seed or a swap below min_out costs only gas.

Seed (once, from the pool's seeder, the pool's token)

{"Seed": {"pool_id": "<id or token|quote|platform>", "expect_creator": "<account>"}}

expect_creator binds the seed to the creator the seeder expects; if the pool names someone else, the seed is refused.

Swap (either side of a seeded pool)

{"Swap": {"pool_id": "<id or token|quote|platform>", "min_out": "<raw units>", "recipient": null, "builder": null}}

recipient defaults to the sender. builder earns the platform's builder_bps only if the platform approved it; otherwise that leg stays with the platform.

Methods

Views

Events

NEP-297 logs with standard: "routr", version: "1.0.0". Amounts are strings of raw units.

Errors

Fees and terms

A pool charges fee_bps (1 to 1,000) of the quote leg of each swap. From that fee the protocol takes protocol_fee_bps (2,000 today, capped at 3,000 in the code). The remainder is the platform's: creator_bps of it goes to the pool's creator, builder_bps of it to an approved builder named on the swap, and the rest to the platform's recipient. Every leg is visible in quote_swap before signing and in the swap event after.

Storage and payouts

Output and fee shares are liabilities first: a swap's output is recorded as pending while its transfer is in flight and becomes owed if the transfer fails (for example an unregistered recipient). push pays anything owed, for anyone, at any time. Claim records cost storage that traders do not attach, so each platform's bond is its own credit, charged per new claim record its pools create; a platform whose credit is spent has its pools' swaps refused until someone tops it up. The contract also checks the venue's shared storage room before accepting a swap. The payout callback is written not to panic: it uses saturating arithmetic and emits invariant_broken instead, so monitor get_pending, get_owed and that event.

Deployments

Current reproducible CI build of the routr contract: code hash H4G6bhZXHKnhecs6gwgL3fQ4F3pt4RPHw34L2uaVhWdN (331,716 bytes, commit 76c5992). This is the build routr.near runs; see Security to check it.