> For the complete documentation index, see [llms.txt](https://docs-v4.nftx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v4.nftx.io/gacha/run-your-own-machine.md).

# Run Your Own Machine

A builder's guide to standing up and operating a gacha machine — creating it, pricing it, curating inventory, and reading its data.

Gacha is built to be run by more than just NFTX. A machine is a first-class, owner-created entity: its collection set, its economics, and its guard rails are all yours to configure. This page is the operator's walkthrough — how a machine comes to life, the levers you set, and how to read what it's doing.

{% hint style="warning" %}
**Testnet only.** Gacha is live today only on **Ethereum Sepolia** (chain `11155111`) as a rehearsal — there is no mainnet deployment yet. Rehearse everything below on Sepolia first.
{% endhint %}

{% hint style="info" %}
**What "your own machine" means today.** Creating a machine is gated to the vault's owner, and the vault custodies real user NFTs — so it can't be ownerless. In practice there are two honest paths: **(1)** NFTX creates and operates a machine to your spec on the shared gacha deployment, or **(2)** you deploy your *own* [NFTXGachaVault](/contracts/gacha-vault.md) + [NFTXGacha](/contracts/gacha.md) pair and operate it yourself. Runtime, permissionless self-registration on a shared deployment is a future enhancement, not today's model. Either way, the machine mechanics below are identical.
{% endhint %}

## Standing up a machine

{% stepper %}
{% step %}

### Create the machine

Call `createMachine(collections, unitCap)` on the vault. You pass the curated list of collection addresses the machine will accept (up to **30**) and a per-collection **unit cap** (how many units any one bucket may hold; default guidance `100`). This mints the machine and returns its `machineId`.

A machine is a **quality band that you curate**. The harmonic-mean pricing means a cheap collection dominates the draw and pulls the whole machine's price toward its floor, so choose the band deliberately. The protocol doesn't cap how wide the band may be — you can build a lottery-style machine that spans cheap floors and rare grails — but the wider the spread, the more the odds concentrate on the cheap end and the rarer the dear pulls become.
{% endstep %}

{% step %}

### Set the pricing and guards

Call `setMachinePricing(machineId, pricing)` on the gacha with a `MachinePricing` struct. This is where the economics and the safety rails live:

| Field                     | Default            | What it does                                     |
| ------------------------- | ------------------ | ------------------------------------------------ |
| `vigBps`                  | `2000` (20%)       | The house edge — which is the depositor yield    |
| `protocolFeeBps`          | `500` (5%)         | Skimmed off spin revenue at claim                |
| `maxBucketWeightShareBps` | `2000` (20%)       | Cap on any one bucket's share of the draw        |
| `twapWindow`              | `1800` (s)         | The oracle window every bucket prices over       |
| `minMachineEV`            | \~50% of launch EV | Fail-closed tripwire; spins stop if EV collapses |

A machine with no pricing set can't be spun — a spin under all-zero parameters would sell at bare EV with every guard disarmed, so it's refused outright.
{% endstep %}

{% step %}

### Wire the oracle and randomness

Set each collection's minimum pool liquidity (`setMinLiquidity`) so a thin, manipulable pool can't be priced against, and confirm the VRF configuration (coordinator, key hash, subscription, confirmations, callback gas). Pricing **hard-fails** on an oracle that's invalid, too shallow, too stale, or backed by too little history — it never falls back to spot. Fund the VRF subscription; the per-spin RNG surcharge tops it up from there.
{% endstep %}

{% step %}

### Activate it

Call `setMachineActive(machineId, true)`. Deactivating later blocks new spins and new deposits, but never traps anyone: pending spins still resolve and claim, and withdrawals, harvests, and refunds are never pausable.
{% endstep %}

{% step %}

### Seed inventory

A machine needs stock before it can be spun — at least the inventory floor of `max(10, 5 × pulls)` drawable units per batch. You can seed it yourself by depositing, but the intended engine is **depositors chasing the vig**: publish the machine, and yield-seekers stock it. There's no restock loop, so a live machine's health is a function of the yield it pays.
{% endstep %}
{% endstepper %}

## Making it show up in the NFTX app

The protocol tracks a machine by numbers — machine IDs and collection addresses. It has no notion of a machine's *name*, art, or accent colour. Those presentation details live in a small, version-controlled metadata file shipped with the NFTX read API, keyed by `{chainId}-{machineId}`. A machine with no entry still works and still serves data; it just renders with a generated name and no art.

To have your machine present with a proper name and artwork in the NFTX frontend, submit a metadata entry (name, symbol, description, image, banner, accent) to be included with the API deploy. It's a code change today, not a runtime write — self-serve metadata is a candidate future enhancement. See [Data & API](/gacha/data-and-api.md#machine-metadata) for the exact fields.

## Operating levers

Beyond setup, the owner surface on the two contracts lets you tune a running machine — change the unit cap, adjust pricing (changes apply from the next snapshot only, never repricing a pending spin), re-point the hook / zap / VRF coordinator if an upstream address changes, and set the protocol fee receiver, claim tip, and RNG surcharge estimate. The full reference is on the [NFTXGacha](/contracts/gacha.md) and [NFTXGachaVault](/contracts/gacha-vault.md) pages.

{% hint style="warning" %}
Operating a machine means custodying other people's NFTs and setting the guards that keep pricing safe. The guard defaults exist for good reasons — read the [oracle-manipulation surface](/gacha/how-it-works.md#machines-are-quality-bands) before loosening the weight cap or `minMachineEV`. Gacha is pre-mainnet; rehearse on Sepolia first.
{% endhint %}

## Reading a machine

Everything a machine does is readable two ways, and third parties are free to use either:

* **The NFTX read API** — the same public "SDK" the NFTX app uses. `GET /v1/{chain}/gacha/machines` and friends return machines, stock, pulls, and activity, with rarity and APR already computed for you. No API key required.
* **Contract read views** — `quote`, `machinePricing`, `snapshotInputs`, `drawableUnits`, `pendingRewards`, and the rest, straight off-chain, when you want ground truth without the indexer.

Both are documented on the next page.