> ## 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.

# Preview calls

> Launch, open, pack and fee calls that the API will serve next

> [!WARNING]
>
> The calls on this page are **not served yet**. Do not call them. Gabox documents them now so you can plan your app. Their shape can still change before they go live. Until then, users take these steps on [gabox.fun](https://gabox.fun).

Each build call answers a transaction for your user to sign. The API never signs, and it never holds a key. Your app's wallet signs the transaction and sends it to Solana. Every transaction spends real money on mainnet, so show your user what it does and what it costs before they sign.

The build calls will need an [API key](https://docs.gabox.fun/developer/limits-and-errors.md#api-keys). A key's limit for builds is 20 a minute, with a burst of 5.

In the samples below, `post`, `get`, `signAndSend` and `sleep` stand for a few lines of your own: a JSON `fetch`, your wallet kit's sign-and-send, and a timer.

## Launch a machine

```http theme={null}
POST /v1/machines/build
```

Builds the launch transaction. One transaction makes the new coin and opens its machine. The creator's wallet and the new mint both sign it, and the creator sends it. See [Launch a machine](https://docs.gabox.fun/launch-a-machine.md).

**creator** `address` *required*

The wallet that launches the coin and pays the launch cost. It earns the creator fee, less the machine's share when `rechargeBps` is set.

**mint** `address` *required*

The public key of a new keypair that your app makes. Its secret key never leaves your app. It signs beside the creator.

**name** `string` *required*

The coin's name, up to 32 bytes.

**symbol** `string` *required*

The ticker: capital letters and digits, up to 10.

**imageUrl** `https URL` *required*

The coin's image. Gabox stores it with the coin's metadata, and the transaction pays that cost back.

**quote** `string` *required*

What packs are priced in: `SOL`, `USDC`, or the mint of another enabled quote token.

**seed** `number`

Extra starting coins for the prize vault, paid in the quote token you picked. For example, 250 means 250 USDC on a USDC machine. It buys the coin at launch, on top of the small seed every machine gets. Leave it out for none.

**rechargeBps** `integer`

[Machine recharge](https://docs.gabox.fun/machine-recharge.md): the machine's share of the coin's creator trading fee, in basis points from 1 to 10,000. 10,000 is all of it. That share buys the coin into the prize pool. Only the launch can turn it on. Later the share can go up, never down. The creator claims the rest. Leave it out to keep the whole fee.

```js theme={null}
import { generateKeyPairSigner } from "@solana/kit"

const API = "https://actions.gabox.fun/v1"
const mint = await generateKeyPairSigner() // your coin; its key stays here

const { data } = await post(`${API}/machines/build`, {
  creator: wallet.address,
  mint: mint.address,
  name: "Lucky Cats",
  symbol: "LUCKY",
  imageUrl: "https://example.com/lucky-cats.png",
  quote: "USDC",
  seed: 250, // optional extra seed, in the quote token (here USDC)
  rechargeBps: 5_000, // optional: half the creator fee refills the prize pool
})

await signAndSend(data.transaction, [wallet, mint]) // you sign, Gabox never does
// gabox.fun/<data.pool> is live: one transaction
```

Sample answer:

```json theme={null}
{
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...",
    "signers": ["<creator wallet>", "<new mint public key>"],
    "pool": "<new machine pool>",
    "metadataUri": "https://gateway.irys.xyz/<id>",
    "expiresAt": "2026-10-10T12:01:30.000Z"
  },
  "meta": { "apiVersion": "1", "cluster": "mainnet-beta" }
}
```

| Field | Description |
| - | - |
| `transaction` | The transaction, base64 encoded, for the creator and the mint to sign. |
| `signers` | The addresses that must sign. |
| `pool` | The new machine's address. |
| `metadataUri` | Where the coin's metadata is stored. |
| `expiresAt` | Send the transaction before this time. After it, build a new one. |

## Open a machine on a coin

```http theme={null}
POST /v1/token-machines/build
```

Builds the transaction that opens a [fan coin machine](https://docs.gabox.fun/fan-coin-machines.md) on a coin that already exists, such as BONK. The creator signs it, and the seed comes from their own coins. Nothing is bought.

**creator** `address` *required*

The wallet that opens the machine. It pays the cost, puts in the seed and earns 1.20% of every pack, or 1.50% when the buyer has no referrer.

**mint** `address` *required*

The coin: any classic SPL Token coin, or a Token-2022 coin that is not paused and has no transfer hook program or transfer fee. Not USDC.

**seed** `number` *required*

The starting coins for the prize vault, in whole coins. They come from the creator's wallet.

**lockSeed** `boolean`

`true`, the default, keeps the seed in the prize pool for good. `false` makes it the creator's deposit: they can take back what is left of it later, but only while no pack is opening and no prize waits for a claim.

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

const { data } = await post(`${API}/token-machines/build`, {
  creator: wallet.address,
  mint: COIN, // a coin that already exists, for example BONK
  seed: 1_000_000, // whole coins, from your own wallet
  lockSeed: true, // false: you can take the seed back later
})

await signAndSend(data.transaction, [wallet])
// gabox.fun/<data.machine> is live
```

Sample answer:

```json theme={null}
{
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...",
    "signers": ["<creator wallet>"],
    "machine": "<new machine address>",
    "expiresAt": "2026-10-10T12:01:30.000Z"
  },
  "meta": { "apiVersion": "1", "cluster": "mainnet-beta" }
}
```

| Field | Description |
| - | - |
| `transaction` | The transaction, base64 encoded, for the creator to sign. |
| `signers` | The addresses that must sign: only the creator. |
| `machine` | The new machine's address. |
| `expiresAt` | Send the transaction before this time. After it, build a new one. |

## Open a pack

```http theme={null}
POST /v1/packs/build
```

Builds one pack's buy transaction for the buyer to sign. The answer names the draw that the pack opens, so you can [follow it](https://docs.gabox.fun/developer/draws.md#follow-a-draw).

**buyer** `address` *required*

The wallet that pays, signs and gets the prize.

**machine** `address` *required*

The machine's address.

**pack** `integer` *required*

The pack's size in whole USDC. It must be one of the sizes in [`/v1/program`](https://docs.gabox.fun/developer/stats-and-program#fixed-pack).

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

const { data: program } = await get(`${API}/program`)
const smallest = Number(BigInt(program.fixedPacks[0].nominalUsdc) / 1_000_000n)

const { data } = await post(`${API}/packs/build`, {
  buyer: wallet.address,
  machine: MACHINE,
  pack: smallest, // whole USDC
})
await signAndSend(data.transaction, [wallet])

let draw = await get(`${API}/draws/${data.draw}`)
while (!draw.data.settled) {
  await sleep(1000) // MagicBlock answers in seconds
  draw = await get(`${API}/draws/${data.draw}`)
}
console.log(draw.data.results) // the tier and the coins won
```

Sample answer:

```json theme={null}
{
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...",
    "draw": "<draw address>",
    "tokenFloor": "912000000",
    "topPrizeFloor": "9120000000",
    "expiresAt": "2026-10-10T12:01:30.000Z"
  },
  "meta": { "apiVersion": "1", "cluster": "mainnet-beta" }
}
```

| Field | Description |
| - | - |
| `transaction` | The transaction, base64 encoded, for the buyer to sign. |
| `draw` | The draw account that the pack opens. |
| `tokenFloor` | The fewest coins the vault must receive for this pack. The transaction signs it. |
| `topPrizeFloor` | The smallest top prize the buyer accepts. The transaction signs it. |
| `expiresAt` | Send the transaction before this time. After it, build a new one. |

The buyer pays in USDC. If the market moved and a signed limit no longer holds, the program refuses the purchase and nothing is bought. See [What you sign](https://docs.gabox.fun/opening-a-pack.md#what-you-sign).

## Creator fees

A launch machine's creator earns part of every trade of its coin: 0.96% on the curve, and about 0.72% after graduation. A coin launched before 29 October 2026 keeps 0.495% and about 0.25%. With [Machine recharge](https://docs.gabox.fun/machine-recharge.md), the machine takes its share of that fee first. A fan coin machine's creator earns 1.20% of every pack on it, or 1.50% when the buyer has no referrer. The creator can claim these fees any time. See [Referrals and earnings](https://docs.gabox.fun/referrals-and-earnings.md#creator-earnings).

### Read claimable fees

```http theme={null}
GET /v1/fees/{wallet}
```

What a creator can claim now: the trading fees of each coin they launched, their part of each Machine recharge fee, and their share of the packs on each machine they opened.

**wallet** `address` *required*

The creator's wallet.

Sample answer:

```json theme={null}
{
  "data": {
    "creator": [
      {
        "mint": "<coin mint>",
        "quoteMint": "<quote mint>",
        "claimable": "1820000"
      }
    ],
    "recharge": [
      {
        "machine": "<machine address>",
        "quoteMint": "<quote mint>",
        "claimable": "32500000"
      }
    ]
  },
  "meta": { "apiVersion": "1", "cluster": "mainnet-beta" }
}
```

Each `creator` row is one coin. Each `recharge` row is one machine with Machine recharge, and its `claimable` is the creator's part of that machine's fee. `claimable` is in the base units of `quoteMint`.

### Claim fees

```http theme={null}
POST /v1/fees/claim/build
```

Builds one transaction that claims every creator fee a wallet can claim, Machine recharge parts included, for that wallet to sign.

**wallet** `address` *required*

The creator's wallet. It signs the claim.

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

const { data } = await post(`${API}/fees/claim/build`, {
  wallet: wallet.address,
})
await signAndSend(data.transaction, [wallet]) // every creator fee, one signature
```

Sample answer:

```json theme={null}
{
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...",
    "expiresAt": "2026-10-10T12:01:30.000Z"
  },
  "meta": { "apiVersion": "1", "cluster": "mainnet-beta" }
}
```

## Selling coins

The API has no sell call. A winner sells the coin with a normal swap, for example on Jupiter. See [Keep or sell](https://docs.gabox.fun/keep-or-sell.md).


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