> For the complete documentation index, see [llms.txt](https://docs.stoxa.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoxa.app/using-the-protocol/spinning.md).

# Spinning

### Buying a spin

You pay in **BNB**. Everything downstream is priced in USDT, but you never have to hold it.

```solidity
ZapRouter.spinWithBNB(uint8 packId, address player) payable
```

In one transaction the router:

1. carves out the Chainlink VRF fee from your `msg.value`
2. wraps the rest to WBNB
3. swaps **exactly** the pack price into USDT on PancakeSwap V3
4. calls `spin()` on the Machine
5. **refunds every leftover wei of BNB**

It is an exact-output swap, so you pay the pool's price for the pack and not a wei more. Overpay deliberately if you like, the change comes straight back.

### Packs

| Pack   | Price         | Reserved per in-flight spin | Status                      |
| ------ | ------------- | --------------------------- | --------------------------- |
| Small  | **8.88 USDT** | 78.85 USDT                  | ✅ live                      |
| Medium | 88 USDT       | 781.44 USDT                 | ✅ live                      |
| Large  | 888 USDT      | 7,885.44 USDT               | ❌ disabled until pool grows |

The odds and face multiples are **identical on every pack**. A legendary is 8.88× whatever you paid. Bigger packs are bigger stakes, not better odds.

{% hint style="info" %}
The large packs are disabled until the bankroll can back their reservations. An enabled pack the vault cannot cover would revert inside `BankrollVault.reserve` with nothing explaining why, so they stay off until the depth is there.
{% endhint %}

### Batch spins

```solidity
ZapRouter.spinBatchWithBNB(uint8 packId, address player, uint8 count) payable
```

Up to **5 spins on one signature**.

The USDT leg is a **single swap for the whole batch** rather than `count` separate ones fewer fees, and one trip through the pool instead of walking the price up against yourself.

Each spin still gets its own VRF request, its own reservation and its own independent settlement. **A batch is N spins bought together, not one spin with N outcomes.** They can land on different tiers and settle in any order.

Everything unspent comes back as BNB.

***

### What happens next

Your spin is recorded as `Pending` and a Chainlink VRF request goes out. Typically a few seconds later the coordinator calls back and the outcome is decided.

Nobody knows the result before that callback — not you, not the operator, not a validator — because it does not exist yet. See How It Works.

#### You win a card

The Machine picks a tier, picks a card uniformly from that tier's rack, pops it off, and transfers the NFT to you. See Cards.

#### The rack was empty

You are paid that tier's **face value in USDT** instead, claimable immediately. Same value, different form and it can always pay, because that money was reserved before your spin was accepted.

#### You hit the jackpot tier

0.05% of spins. The whole growing jackpot card is yours, plus any unswapped fund. See Jackpot & Golden Egg.

#### Chainlink never answers

After **2 days**, `cancelSpin(spinId)` refunds the entire pack price. It is permissionless and  anyone can call it for anyone, and it needs no operator action. Fees are only taken at settlement, so a cancelled spin costs you nothing but gas.

***

### Claiming USDT

Cash winnings fallback payouts, golden egg wins, consignment payouts are booked as **credits** rather than pushed to you.

```solidity
credits(address) → uint256
claim(address to)
```

This is deliberate. Settlement runs inside the VRF callback, and a callback that reverts is never redelivered, it would strand the spin, holding its reservation until someone cancels it. Booking a credit cannot fail, so nothing a winner does can brick another player's settlement.

Cards transfer directly, using a raw transfer with no receiver hook, for the same reason.

### Concurrency

Every in-flight spin holds its reservation until it settles. With `$X` unreserved in the vault, the machine supports `floor(X ÷ 78.85)` concurrent 8.88 spins; further attempts revert until one settles.

That is a limit on **simultaneous** spins, not total ones. Reservations are released at settlement, and 96% of every pack price flows into the vault, so capacity grows as people play.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stoxa.app/using-the-protocol/spinning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.