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

# Quickstart

> One call that tells you whether a contract address is safe to act on.

Somebody hands your product a contract address. Not a ticker, a string, which is how a fake actually reaches a user. One call answers it.

```bash curl theme={null}
curl https://stonkpile.xyz/api/verify/XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB
```

```js JavaScript theme={null}
const mint = "XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB";
const res = await fetch(`https://stonkpile.xyz/api/verify/${mint}`);
const v = await res.json();

if (!v.clear) {
  // Do not show this as a tokenized stock.
}
```

```python Python theme={null}
import requests

mint = "XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB"
v = requests.get(f"https://stonkpile.xyz/api/verify/{mint}").json()

if not v["clear"]:
    ...  # do not show this as a tokenized stock
```

```json Response theme={null}
{
  "mint": "XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB",
  "verdict": "issued",
  "clear": true,
  "symbol": "TSLAx",
  "name": "Tesla",
  "issuer": "xStocks",
  "underlying": "TSLA",
  "hasMarket": true,
  "liquidity": 1701317,
  "feed": "247",
  "perpVenues": ["Phoenix", "Hyperliquid"],
  "rating": { "score": 87, "band": "prime" }
}
```

## Branch on `verdict`, not on prose

`verdict` is one of four values and never anything else.

| `verdict` | What it means |
| - | - |
| `issued` | An issuer's own token, verified by the host serving its metadata |
| `quoted_coin` | A real token, but not a stock: something priced against one |
| `impostor` | Wears a stock's ticker and no issuer published it |
| `unknown` | Not in the index. An answer, not an error |

`clear` is the same judgement as a boolean, for the common case where you only need to decide whether to proceed.

> [!WARNING]
>
> Every well formed request returns **200**, including `unknown` and `impostor`. Those are answers, not failures. A client that treats a 404 as a transport error will retry its way into exactly the purchase this is meant to prevent.

## Verified is not the same as tradeable

A token can be perfectly real and still have nobody on the other side of it. Most of them are. Check `hasMarket` before you imply somebody can buy or sell.

```js theme={null}
if (v.clear && v.hasMarket && v.rating?.score >= 62) {
  // real, has a market, and the market is sound or better
}
```

See [The rating](https://stonkpile.xyz/docs/concepts/rating.md) for what the score and the bands mean.

## Next

> [card] [The whole index](https://stonkpile.xyz/docs/api/full-index.md)
>
> Every listing and the category totals in one response.

> [card] [MCP server](https://stonkpile.xyz/docs/mcp.md)
>
> The same checks as tools an agent can call.


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