SDK reference

Install and connect

import { Rare } from "@rare/sdk";

const rare = await Rare.connect({ game: "my-game" });
console.log(rare.transport); // "launcher-web", "launcher-native" or "web"

Rare.connect(options) finds a transport and returns a client. With no launcher it falls back to the web transport, which needs game. It throws no_transport only when you force a transport that is not there.

Every call takes an optional last argument { signal, timeoutMs }. An aborted signal throws aborted.

Amounts are in MIST. Inputs accept a bigint, a safe-integer number or a string of digits. Results that carry an amount (receivedMist, a notice's amountMist) are bigint. An ItemCard keeps the API's shape, where amounts are decimal strings.

Calls

me

const me = await rare.me();
// { address, username, network, canSign }

canSign is false when the account can only watch. On the web transport address is the one you passed and canSign is false.

inventory

const items = await rare.inventory(); // ItemCard[]

The player's items from this game only: its registered collections and classes. Each is an ItemCard as the Items API returns it (id, name, type, imageUrl, collection, listing, lastSaleMist, topOfferMist, owner, and more).

sell

const r = await rare.sell({ itemId, mode: "best-offer" });
// { status: "sold", digest, receivedMist }

status is sold, listed, cancelled or unavailable. The web transport answers pending.

buy

await rare.buy({ itemId });
await rare.buy({ collection: itemType, kind: 3, maxMist: 2_000_000_000n });

Pass an itemId, or a collection (a Move type or slug) to take the cheapest listing, optionally of one kind and under maxMist. status is bought, cancelled or unavailable, with digest and itemId when bought. The web transport answers pending.

claim

const r = await rare.claim(voucherToken);
// { status: "claimed", digest, objectId }

Submits a voucher your server signed: an item, an item state change or a trophy. The player confirms a one-line sheet and gas is paid where the game's budget allows. Pass the token string from the server. Both base64 and base64url are accepted. status is claimed, cancelled, rejected (the chain would refuse it: expired, wrong player, already used) or unavailable. The web transport answers pending.

open

await rare.open({ view: "trophies" });

view is item, collection, trophies, store or overlay, with an id for item and collection. Off the device the web transport opens the matching rare.market page. overlay only exists in Rare Launcher.

licence

const l = await rare.licence(); // { owned, edition?, lease? }

Rare Store ownership for this game. Only available in Rare Launcher.

Notices

const off = rare.on("notice", (n) => toast(n.title));
rare.on("error", (e) => console.warn(e));
off();       // stop this handler
rare.close(); // stop the stream

The first handler starts the stream and the last one to leave stops it. A notice has id, kind, title, body, itemId, amountMist, digest and the full raw object. Kinds for a game's items are offer_received, sold and bought. On the web transport the stream is /notify/stream for the player's address, which is also how a pending sheet reports its result.

Errors

Every error is a RareError with a code, and status and remoteCode when the other side sent them. Use isRareError(e) to narrow.

Server

import { gameKey, itemVoucher, stateVoucher, trophyVoucher, verifyVoucher, RareApi } from "@rare/sdk/server";

const key = gameKey(process.env.RARE_GAME_KEY!);

Every signing function also takes ttlMs (default 10 minutes), nonce (default 64 random bits) and nowMs (for tests). Each returns a voucher with its fields, sig (64 bytes) and token, the string you send to the game client. See Voucher signing.

RareApi

const api = new RareApi({ apiKey: process.env.RARE_API_KEY });
const { items } = await api.items({ owner: player, game: "my-game" });
const owns = await api.owns(player, itemId, "my-game");
const game = await api.game("my-game");

A small client for server-side ownership checks. With game, items returns that game's items from the player's cross-game inventory. Without it, it pages every collectible the address holds. Options: apiKey, baseUrl, network, fetch, timeoutMs. Errors are RareError.