> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gabox.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Common tasks

> Short recipes for the things most Gabox apps do

Every recipe uses only live routes and needs no key. `API` is `https://actions.gabox.fun/v1`.

## Find a machine

List the machines and follow `page.nextCursor`. Then read one machine for its packs, prize tiers and vault. Read `account` first: a launch machine (`Pool`) and a fan coin machine (`TokenMachine`) have different fields.

```js theme={null}
const API = "https://actions.gabox.fun/v1"

const { data: machines } = await (await fetch(`${API}/machines?limit=50`)).json()
const open = machines.filter((m) =>
  m.purchasesOn &&
  (m.account === "Pool" ? m.stage !== "migrating" && m.offer : m.packQuotes.length > 0),
)
```

A machine's page on the website is `https://gabox.fun/<address>`, built from the machine's `address` field. Every machine route takes that `address` too. A coin's mint finds only the coin's launch machine. To list every machine on one coin, add `?mint=<mint>` to the list route. If a user pastes a page link, its last part is the machine's `address`.

## Show a machine card

A card usually shows the coin, the price of the cheapest pack, the top prize and the packs opened.

```js theme={null}
function formatUnits(raw, decimals) {
  const value = BigInt(raw)
  const scale = 10n ** BigInt(decimals)
  const fraction = (value % scale).toString().padStart(decimals, "0").replace(/0+$/, "")
  return fraction ? `${value / scale}.${fraction}` : `${value / scale}`
}

const { data: m } = await (await fetch(`${API}/machines/${MACHINE}`)).json()

const card = {
  title: `${m.name} (${m.symbol})`, // creator text: show it, never run it
  image: m.imageUrl,
  priceSol: m.offer?.solAmount ? formatUnits(m.offer.solAmount, 9) : null,
  topPrize: m.offer ? formatUnits(m.offer.maximum, m.tokenDecimals) : null,
  packsOpened: m.stats.pullsTotal,
  link: `https://gabox.fun/${m.address}`,
}
```

Only a launch machine has `offer`. On a `TokenMachine`, each entry of `packQuotes` is one pack price in USDC base units and the coins it buys now.

The API sends the coin's decimals in `tokenDecimals`. It does not send the quote token's decimals. USDC has 6 and SOL has 9. For another quote token, read its mint's decimals from Solana, or show `offer.solAmount` in SOL.

## Show the odds

The chance of each prize row is `tickets / 65536`. On a launch machine, the live prize amounts are in `offer.prizes`, in the same order as `tiers`. A `TokenMachine` has no `offer`, so show its chances and multipliers only. Skip rows with 0 tickets.

```js theme={null}
const rows = m.tiers
  .map((tier, index) => ({ tier, prize: m.offer?.prizes[index] }))
  .filter(({ tier }) => tier.tickets > 0)
  .map(({ tier, prize }) => ({
    chance: `${((tier.tickets / 65536) * 100).toFixed(2)}%`,
    multiplier: `${tier.multiplierBps / 10000}x`,
    coins: prize ? formatUnits(prize.amount, m.tokenDecimals) : null,
  }))
```

A multiplier can pay less when the vault is low, so show `offer.prizes`, not your own maths, as the amount. See [Prizes and odds](https://docs.gabox.fun/prizes-and-odds.md).

## Follow a draw

Ask `GET /v1/draws/{address}` about once a second until `settled` is `true`. Then `prizeTier` is the prize row and `amount` the coins paid. See [Draws](https://docs.gabox.fun/developer/draws.md#follow-a-draw) for the full loop.

## Show live activity

For a feed of one machine's packs, read `GET /v1/machines/{machine}/pulls` every few seconds. A pull's `payout` is `null` until its draw settles, so show it as "waiting" first.

```js theme={null}
let seen = new Set()

async function poll() {
  const { data: pulls } = await (await fetch(`${API}/machines/${MACHINE}/pulls?limit=10`)).json()
  for (const pull of pulls.reverse()) {
    const key = `${pull.seq}:${pull.payout ?? "waiting"}`
    if (seen.has(key)) continue
    seen.add(key)
    console.log(pull.purchaser, pull.payout ?? "waiting")
  }
}

setInterval(poll, 5000) // 12 reads a minute stays under the limit without a key
```

For the biggest wins on every machine, read `GET /v1/pulls/top`. For totals, read `GET /v1/stats`.

If many people use your app at once, read on your server and share the answer with every visitor. Answers may be cached for 5 seconds anyway. See [Limits and errors](https://docs.gabox.fun/developer/limits-and-errors.md#rate-limits).

## Check a seed lock

`seedLocked` says whether the creator can take the seed back. `true` means nothing can withdraw it, and a launch machine is always `true`. On a `TokenMachine`, `false` means the seed is the creator's deposit, and `null` means the index has not read it yet. See [Seed and jackpot](https://docs.gabox.fun/seed-and-jackpot.md).

## Check Machine recharge

On a launch machine, `recharge` is `null` when [Machine recharge](https://docs.gabox.fun/machine-recharge.md) is off. Otherwise, `recharge.machineBps` is the machine's share of the creator trading fee, and `recharge.coinsAdded` is the coins it has bought for the prize pool so far.

```js theme={null}
const { data: m } = await (await fetch(`${API}/machines/${MACHINE}`)).json()

if (m.account === "Pool" && m.recharge) {
  const share = `${m.recharge.machineBps / 100}%`
  const added = formatUnits(m.recharge.coinsAdded, m.tokenDecimals)
  console.log(`${share} of the creator fee refills the prize pool. ${added} coins so far.`)
}
```

The [recharge object](https://docs.gabox.fun/developer/machines.md#the-recharge-object) lists every field.

## Explain a machine with an AI

`GET /v1/machines/{machine}/brief.md` answers one machine as Markdown, ready for an AI. To give your agent the whole API, install the [Gabox skill](https://docs.gabox.fun/developer/agent-skill.md):

```bash theme={null}
npx skills add gabox-labs/skills -g
```

## Launch a coin, open a machine on a coin, open a pack, claim fees

These calls are [Preview](https://docs.gabox.fun/developer/preview-calls.md). Until they are live, send your users to [gabox.fun](https://gabox.fun) for these steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.