Quickstart

Everything below runs against your own game server. GameFi Rails is a server-to-server API: your backend already knows who the player is, so there is no wallet connect, no signature prompt, and no key material anywhere near the game client.

1 · Install

npm install @gamefi-rails/sdk-js

2 · Instantiate the client

baseUrl points at the API (port 7300 in the sandbox). apiKey is optional: omit it and the request runs against the shared sandbox tenant, which is exactly what the public demo pages do.

import { GameFiClient, GameFiError } from '@gamefi-rails/sdk-js';

const gamefi = new GameFiClient({
  baseUrl: 'http://localhost:7300',
  apiKey: process.env.GAMEFI_API_KEY,  // server-side only — never in a build
  retries: 2,                        // network + 5xx only; 4xx is terminal
});

3 · Create a player

You identify players by whatever id your game already uses — a Steam id, an account uuid, an email hash. The call is idempotent: the same externalPlayerId always returns the same playerId, so you can call it on every login without bookkeeping.

const player = await gamefi.createPlayer('steam:12345');
// → { playerId: '9f1c…', tenantPlayerRef: '4b7e…' }

// Sandbox only: 100 USDC of play money so the player can trade.
await gamefi.faucet(player.playerId, 'USDC');

4 · Reward gameplay

Rewards are the mint path for your game token — server-side only, since calling this creates supply. Each call posts a ledger transaction against system:mint:DRAGON, so emissions are auditable rather than a counter somebody incremented.

await gamefi.reward(player.playerId, 'boss-slain');
// → { earned: '25 DRAGON' }   ('dragon-slain' pays 5)

// Loot becomes a tradable asset the player owns outright
const loot = await gamefi.mintNft(player.playerId, 'swords', 'Ember Fang');
await gamefi.listNft(player.playerId, loot.assetId, '15');

5 · Place an order

The player now has a balance worth selling. Orders go on a real price-time-priority order book; the call returns as soon as funds are reserved and the command is durably queued, which is why it answers 202 Accepted with status: 'PENDING' rather than a fill.

try {
  const order = await gamefi.placeOrder({
    playerId: player.playerId,
    pairId:   1,          // DRAGON/USDC
    side:     'Sell',
    orderType: 'Limit',
    price:    '2.40',     // whole USDC per whole DRAGON
    qty:      '10',       // whole DRAGON
  });
  // → { clientOrderId: '…', status: 'PENDING', reserved: '10000000 DRAGON (minor)' }
} catch (e) {
  if (e instanceof GameFiError && e.code === 'INSUFFICIENT_FUNDS') { /* … */ }
  throw e;
}

// Watch it fill. The stream replays history, so this is complete.
const stop = gamefi.events(({ pairId, event }) => {
  if (event.type === 'Trade') console.log(pairId, event.qty, event.price);
});

Authentication

Every authenticated request carries a studio API key in the x-api-key header. The SDK adds it for you when you pass apiKey to the constructor.

POST /v1/players
x-api-key: gfr_9c1f0b7a4e2d…
content-type: application/json

Minting a key

Keys are created together with the tenant at POST /v1/tenants. The response is the only time the plaintext key exists outside your control: the server stores just sha256(key) in api_keys.keyHash and compares hashes on every request. There is no "show key again" endpoint because there is nothing left to show — a leaked database gives an attacker hashes, not credentials. Lose the key and you mint a new one.

{
  "tenantId": "3f2a…",
  "apiKey": "gfr_9c1f0b7a4e2d…",
  "note": "store the key now — it is not shown again"
}

What a key resolves to

A valid key resolves to your tenantId, and that tenant scopes your players, your fee accounts, your listings and your studio metrics. A key that is present but unknown or revoked fails the request with UNAUTHORIZED (401). A request with no key at all falls back to the shared sandbox tenant — convenient for prototyping, but it means a silently dropped header looks like "it works" while writing into the wrong tenant. Assert the header in your own integration tests.

Core concepts

Five ideas explain almost every surprising thing in the API. They are all downstream of one decision: this is accounting infrastructure that happens to serve games, not a game backend that happens to hold money.

Money is an integer, always

Every amount on the wire and in the database is an integer count of minor units — the smallest indivisible piece of the asset. USDC and DRAGON both use 6 decimals, so 1 USDC = 1_000_000 minor units. Floating point never touches a balance: 0.1 + 0.2 is a rounding curiosity in a chart and a lawsuit in a ledger. The SDK surfaces decimal strings ("2.40") at the boundary and converts to integers immediately, so your code never handles a float either.

The price wire format

Prices need more precision than an amount does, so they carry their own scale:

// wire price = quote minor units per ONE WHOLE base unit, × 1e8
2.5 USDC/DRAGON
  → 2.5 × 1e6            // 2_500_000 quote minor per whole DRAGON
  → 2_500_000 × 1e8       // PRICE_SCALE
  = 250_000_000_000_000

// and the one derivation everything settles on:
quoteAmount = (price × qty) / (PRICE_SCALE × 10^baseDecimals)

You send price: "2.5" and the API does this conversion. It matters anyway, because it is the number you will see on the WebSocket stream and in the engine's events. Rounding on that division always goes against the taker — up when the taker pays quote, down when the taker receives it — and the sub-unit residual is posted to system:suspense:rounding rather than quietly vanishing.

Reservations: funds are held before the engine sees the order

POST /v1/orders does five things in a single Postgres transaction: validate the order against the pair's rules, compute the required reserve, insert the reservation row, post the ledger hold moving value from user:{id}:available:{sym} to user:{id}:hold:{sym}, and enqueue the NewOrder command in the transactional outbox. Then it commits.

The ordering is the whole point. The matching engine is fast and in-memory; it cannot ask "does this player still have the money?" at match time without becoming slow and stateful. So the money is already locked before the command can physically reach it — if the hold fails, no command is ever queued, and if the command is queued, the funds provably exist. A buy reserves worst-case notional plus taker fee in the quote asset; a sell reserves the base quantity. That reserve is why the response is 202 PENDING with a reserved figure instead of a fill.

The double-entry ledger

There is no balance column that code increments. Every movement of value — reward, deposit, reserve, trade, royalty, fee — is a transaction whose entries sum to zero per asset. A balance is the running total of entries against an account handle, and a continuous job asserts the zero-sum invariant, so a wrong balance cannot hide; it shows up as a broken book. Handles are readable and structural:

user:{playerId}:available:{symbol}   // spendable
user:{playerId}:hold:{symbol}        // reserved against an open order or listing
tenant:{tenantId}:fee:{symbol}       // your studio's fee revenue
system:mint:{symbol}                 // token issuance (negative = supply outstanding)
platform:fee:{symbol}

User accounts are credit-normal, so raw balances are negative and the API negates them for display. This is also why GET /v1/studio/economy can report emissions, holders, velocity and GMV at all — they are derived from the ledger, which is the source of truth rather than a cache of one.

NFTs are ledger assets

An NFT is not a parallel money system. Minting inserts an asset row with kind = 'NFT', decimals = 0 and a supply of exactly 1, and then posts an ordinary ledger transaction. Because of that, listing an item is just a hold (available → hold, which fails with INSUFFICIENT_FUNDS if the seller doesn't actually own it) and a sale is a single atomic multi-entry post: the buyer's USDC splits across seller proceeds, a 5% creator royalty, and a 2% market fee shared 50/50 between your studio and the platform, while the NFT moves whole in the same transaction. Royalties are enforced at settlement, not by convention — there is no code path where the item transfers and the royalty doesn't.

API reference

Base URL http://localhost:7300 in the sandbox. All request bodies are JSON; all responses are JSON. Fields marked * are required. Errors use the envelope { "error": CODE, "message": "…" } — see Errors.

Studio

{
  "tenantId": "3f2a1c8e-…",
  "apiKey": "gfr_9c1f0b7a4e2d…",
  "note": "store the key now — it is not shown again"
}

{
  "tenantId": "3f2a1c8e-…",
  "feeBalances": { "USDC": "14.203000" },   // whole units, 6dp
  "players": 1284,
  "openReservations": 37              // reservations still HELD
}

{
  "tokenEmissions": "48250.00",        // DRAGON minted via REWARD
  "feeRevenue": "14.20",               // your tenant fee accounts
  "tokenHolders": 612,
  "tradingVolumeQuote": "93110.50",     // settled TRADE volume in quote
  "marketplaceGmv": "7420.00",          // SOLD listings
  "riskEvents24h": 3,
  "haltedPairs": [ { "pairId": 1, "reason": "price_band" } ]
}

Players

{
  "playerId": "9f1c2d70-…",        // use this on every other call
  "tenantPlayerRef": "4b7e…"          // per-tenant opaque alias
}

tenantPlayerRef is sha256(tenantId:playerId) truncated to 32 hex chars. It is safe to write into game saves, logs and analytics because two tenants holding refs for the same underlying player cannot join their datasets on it.

Orders

{
  "clientOrderId": "c1a8…",          // correlates with every stream event
  "status": "PENDING",
  "reserved": "25075000 USDC (minor)"  // 25 USDC notional + 0.075 taker fee
}

A market buy has no price to compute a reserve from, so you must supply maxQuote yourself: it is the ceiling the player agrees to spend, and it is reserved in full up front. Anything unspent is released when the fill settles.

Pair rules (sandbox)

Orders are validated against the pair's limits at the edge using the exact same rules the Rust engine applies, so a rejection is deterministic and arrives as a VALIDATION error rather than an engine round-trip.

Marketplace

{
  "assetId": 318,
  "symbol": "NFT#swords:1a2b3c4d"
}

{
  "nfts": [
    { "assetId": 318, "symbol": "NFT#swords:1a2b3c4d",
      "name": "Ember Fang", "listed": false }
  ]
}

{ "listingId": "7d40e1b2-…" }

{
  "listings": [
    { "listingId": "7d40e1b2-…", "assetId": 318,
      "symbol": "NFT#swords:1a2b3c4d", "name": "Ember Fang",
      "priceMinor": "15000000", "sellerId": "9f1c2d70-…" }
  ]
}

{
  "bought": "NFT#swords:1a2b3c4d",
  "paid": "15.00"
}

How a sale splits

Rewards

{ "earned": "25 DRAGON" }

A 3-second per-player cooldown is enforced server-side; a faster second call returns 429 RATE_LIMITED. It is deliberately crude — a client that can call "I killed a boss" can call it in a loop, so the first brake has to live on the server. The risk engine adds real behavioural scoring on top of it. Call this from your game server after your own authoritative combat resolution, never from the client.

Balances & faucet

{
  "balances": {
    "USDC":   { "available": "74.925000", "hold": "25.075000" },
    "DRAGON": { "available": "25.000000", "hold": "0" }
  }
}

{ "credited": "100 USDC" }

Admin

{ "unhalted": 1 }

WebSocket stream

The matching engine never talks to end users. A gateway consumes the shard's event topic and fans it out as JSON on ws://{host}:7301 — no subscribe message, no auth handshake, no channels. Connect and you receive events.

const stop = gamefi.events(({ pairId, event }) => {
  switch (event.type) {
    case 'OrderAccepted': /* resting on the book */ break;
    case 'Trade':         /* a fill — settlement follows */ break;
    case 'OrderCanceled': break;
    case 'OrderRejected': /* event.reason tells you why */ break;
  }
});
// later
stop();

Every frame is { pairId, event }. The client derives the ws URL from baseUrl by swapping the scheme and the port to 7301; override it with wsUrl if your deployment differs. It reconnects automatically after 1.5s on close.

Full replay on connect

The gateway sends its entire event history to each new client before any live frame. That is intentional: a subscriber can rebuild the complete order book from nothing, so a dropped connection is not a correctness problem, just a reconnect. It also means you should treat your local state as derived — reset and rebuild on every open rather than trying to patch a partial view back together.

Event types

Trade fields

All 64/128-bit integers arrive as JSON strings, not numbers — they overflow IEEE-754 doubles. Parse them with BigInt, never Number.

const seen = new Set<string>();

gamefi.events(({ pairId, event }) => {
  const key = `${pairId}:${event.seq}`;   // NOT event.seq alone
  if (seen.has(key)) return;
  seen.add(key);
  apply(pairId, event);
});

Errors

Failures return a JSON envelope with a stable machine-readable code. Branch on error; the message is for your logs, not your control flow.

{ "error": "INSUFFICIENT_FUNDS", "message": "insufficient available balance" }

Retry semantics

The SDK transport retries network failures and 5xx with exponential backoff — 250 ms, then 500 ms, two attempts by default, tunable with retries. 4xx responses are terminal and throw immediately as a GameFiError carrying code, message and status. That split is the useful one: a 422 will fail identically on the next attempt, while a dropped connection or a restarting node usually won't.

import { GameFiError } from '@gamefi-rails/sdk-js';

try {
  await gamefi.placeOrder({ playerId, side: 'Buy', price: '2.5', qty: '10' });
} catch (e) {
  if (!(e instanceof GameFiError)) throw e;
  switch (e.code) {
    case 'INSUFFICIENT_FUNDS': return showTopUp();
    case 'PAIR_HALTED':        return showMarketPaused();
    case 'VALIDATION':         return showBadOrder(e.message);
    default:                    throw e;   // already retried if retryable
  }
}

Unity SDK

The Unity package speaks the same v1 API with the same typed errors. It hides RPCs, gas, private keys and transaction tracking, so your players never see a wallet popup.

Install

Window → Package Manager → + → Add package from git URL:

https://github.com/<org>/gamefi-rails.git?path=packages/sdk-unity

Or copy the folder into Packages/com.gamefios.sdk. Unity 2021.3+; a sample scene lives in Samples~/Quickstart.

Usage

Every call is a coroutine taking an Action<T> success callback and an optional Action<GameFiError> for failures — drive them with StartCoroutine so nothing blocks the main thread.

using GameFiOS;

public class Economy : MonoBehaviour {
  CreatePlayerResult _player;
  MintResult _loot;

  // Sandbox: no key. Production: your game SERVER holds the key.
  GameFiClient gamefi = new GameFiClient("http://localhost:7300");

  void Start() {
    StartCoroutine(gamefi.CreatePlayer("steam:12345", r => _player = r));
  }

  public void OnBossSlain() {
    StartCoroutine(gamefi.Reward(_player.playerId, "boss-slain",
      r  => Debug.Log(r.earned),
      err => Debug.LogWarning(err.code)));

    // Loot becomes a tradable asset, then goes on the market.
    StartCoroutine(gamefi.MintNft(_player.playerId, "swords", "Ember Fang",
      r => _loot = r));
    StartCoroutine(gamefi.ListNft(_player.playerId, _loot.assetId, "15", _ => {}));

    // Or cash the token out on the order book. DRAGON → USDC.
    StartCoroutine(gamefi.PlaceOrder(_player.playerId, "Sell", "2.4", "10",
      r => Debug.Log(r.clientOrderId)));
  }
}

Available methods: CreatePlayer, Reward, MintNft, ListNft, BuyNft, PlaceOrder and GetBalancesRaw. Amounts are decimal strings on the boundary here too — Unity's float has no business anywhere near a balance.