> 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/cards.md).

# Cards

### What a card is

An ERC-721 certificate minted by the `StockWrapper`, holding a specific quantity of one tokenized stock in escrow.

```
Card #412
  underlying   0.0082 SPYB
  face         $6.22        ← USDT actually spent acquiring it
  pack / tier  8.88 / common
  won at       block timestamp
```

The **face** is not an estimate. It is the USDT the machine spent on the DEX swap that created the card. There is no oracle and no admin-set price, because the payment *is* the minting.

### The escrow floor

The wrapper tracks `totalWrapped` per token, the sum of every live certificate's holdings. Its actual balance can never be swept below that:

```solidity
surplus = balanceOf(this) - totalWrapped[token];
require(surplus > 0, "Wrapper: no surplus");
```

Only genuinely unattributable tokens — a rebase, or something sent by mistake — can be swept by the owner. The shares backing live cards are untouchable.

***

### What you can do with one

#### Hold it

The shares behind it track the real equity. A card minted at $6.22 of NVDA is worth whatever that NVDA is worth later, up or down.

#### Unwrap it

```solidity
unwrap(uint256 certId)
```

Burns the certificate and sends you the raw stock token. Checks that you own it, and nothing else **no pause, no allowlist, no operator involvement.** 

#### Sell it back

For **2 days** after you win it, the house buys it at `face × 97.5%`, paid in **BNB** straight to your wallet.

```solidity
buybackQuote(uint256 certId) → uint256   // 0 if it cannot be sold back
```

Returns `0` rather than reverting when the card is ineligible, so the interface can grey the button out instead of failing on submit.

The window is short on purpose. The buyback is a put struck at a face frozen at acquisition and never re-marked. Unbounded in time, a holder would only ever exercise it on cards whose stock **fell**, keeping the winners and over months a stock can halve. Two days is what makes a frozen strike safe to offer at a 2.5% spread.

#### Split it

```solidity
split(uint256 id, uint256 amount, address to) → uint256 childId
```

Carves part of a card's shares into a new certificate.

{% hint style="danger" %}
**Splitting is permanent and voids the face value.** A split card keeps its shares and its unwrap right, but can **never** be sold back or consigned. The contract enforces this  `sellBack` and `consign` both revert with `CardSplit`.
{% endhint %}

#### Trade it

Cards are ordinary ERC-721s and work on any marketplace. Provenance travels with them: a buyer can read the pack, tier, face and win time straight from `cardMeta`.

A purchased card keeps its unwrap right. It does **not** keep the buyback that belongs to the original winner and expires with the window.

***

### Provenance

```solidity
cardMeta(uint256 certId) → (packId, tierIndex, onRack, face, wonAt)
```

Immutable once won. A legendary pull is verifiable by anyone reading the chain, forever, including after the card changes hands.

### Where cards come from

Only one place: `restock`. The restocker spends `count × face` of vault USDT on a DEX swap and the wrapper mints that many equal-slice certificates.

Face equals acquisition cost by construction. That single property is what enforces the published RTP with no oracle anywhere in the system, the machine cannot create a card worth more than it paid for it.

There was once a second path, for sponsored drops. It was removed: it let a caller supply their own slippage bound and mint arbitrary-face dust cards by self-sandwiching the swap. The function is gone from the deployed bytecode rather than merely gated.


---

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