# woop API v1: complete documentation

Base URL: https://usewoop.xyz/api/v1
Auth: send `Authorization: Bearer <API key>` with every request (keys come from the wallet menu → API key on woop).
OpenAPI 3.1 schema: https://usewoop.xyz/api/v1/openapi.json

Pages in this document:
- woop API: https://usewoop.xyz/docs/api
- Authentication: https://usewoop.xyz/docs/api/authentication
- Launch a coin: https://usewoop.xyz/docs/api/launching
- Trade: https://usewoop.xyz/docs/api/trading
- Exit Queue: https://usewoop.xyz/docs/api/exit-queue
- Creator tools and refunds: https://usewoop.xyz/docs/api/creators
- Read data: https://usewoop.xyz/docs/api/reading-data
- Errors and limits: https://usewoop.xyz/docs/api/errors
- Endpoint reference: https://usewoop.xyz/docs/api/reference
- Objects: https://usewoop.xyz/docs/api/schemas


---

# woop API

Source: https://usewoop.xyz/docs/api

Build on woop. Launch coins on the woopcurve, trade them and read woop's data from your own app.

The woop API (v1) lets your app do what the woop app does: launch coins, trade them, use the Exit Queue and read prices, trades and holders.

Coins you launch through the API are ordinary woop coins. They launch on the woopcurve, graduate into their own WAMM pool, and show on woop with everyone else's: on Pulse, in Coins and on their own coin page.

## How it works

1. **Get a key.** Log in on woop, open the wallet menu and pick **API key**. One key per wallet.
2. **Build.** Ask the API for a launch or a trade. It checks everything and returns a ready transaction.
3. **Sign.** The user's wallet signs it. woop never holds anyone's keys.
4. **Send.** Post the signed transaction to `/api/v1/transactions`, or send it yourself.

```bash
curl https://usewoop.xyz/api/v1/pairs \
  -H "Authorization: Bearer woop_…"
```

## Base URL

```
https://usewoop.xyz/api/v1
```

Every request needs your API key. Every response is JSON.

The full schema is at [`/api/v1/openapi.json`](https://usewoop.xyz/api/v1/openapi.json) (OpenAPI 3.1): import it into Postman or Insomnia, or generate a typed client from it.

## What you can do

| Guide | What it covers |
|---|---|
| [Launch a coin](https://usewoop.xyz/docs/api/launching) | Name, ticker, image and pair, plus an optional description, banner, links and first buy |
| [Trade](https://usewoop.xyz/docs/api/trading) | Buy or sell instantly, or in a Fair Block |
| [Exit Queue](https://usewoop.xyz/docs/api/exit-queue) | Queue a big sell so it fills into buys without dropping the chart |
| [Creator tools](https://usewoop.xyz/docs/api/creators) | Take unlocked coins, lock for longer, refunds |
| [Read data](https://usewoop.xyz/docs/api/reading-data) | Coins, trades, holders, candles, curve state, the queue, positions, payouts, signals, portfolios |
| [Reference](https://usewoop.xyz/docs/api/reference) and [objects](https://usewoop.xyz/docs/api/schemas) | Every endpoint and every field |
| [API docs for AI](https://usewoop.xyz/docs/api/ai) | Copy all of it for Cursor, Claude or ChatGPT in one click |

> **Note** The API launches and trades woopcurve coins only: new coins on the woopcurve and, after graduation, their WAMM pools.

---

# Authentication

Source: https://usewoop.xyz/docs/api/authentication

Get an API key, send it with every request, and rotate it.

## Get a key

1. [Log in](https://usewoop.xyz/docs/wallets) on [usewoop.xyz](https://usewoop.xyz).
2. Open the wallet menu (top right) and pick **API key**.
3. Sign the message your wallet shows. It's free and sends nothing; it only proves the wallet is yours.
4. Press **Create API key**.

The key belongs to that wallet. Coins launched with it are credited to it, and you can see them on the key page and at `GET /api/v1/me`.

## Send it

Put the key in the `Authorization` header:

```bash
curl https://usewoop.xyz/api/v1/me \
  -H "Authorization: Bearer woop_…"
```

`x-api-key: woop_…` works too.

## See it again or rotate it

Come back to **API key** in the wallet menu any time and sign in to see your key. **Rotate key** gives you a new one; the old one stops working straight away.

> **Warning** Keep your key on your server. Don't put it in a public repo or in a website's front-end code: anyone with it can use your limits and launch under your account.

## The key is not a wallet

The key can't move anyone's funds. Every launch and trade is a transaction the user's own wallet has to sign.

---

# Launch a coin

Source: https://usewoop.xyz/docs/api/launching

Launch a coin on the woopcurve from your app. Name, ticker, image and pair are required.

A launch takes the same form as woop's launch page. It goes on the woopcurve, opens with a 60-second fair opening, and shows on woop as soon as it lands.

## 1. Upload the image

Send the coin's picture (PNG, JPG, WebP or GIF, up to 8 MB). woop crops it square and stores it on its CDN.

```bash
curl https://usewoop.xyz/api/v1/uploads \
  -H "Authorization: Bearer woop_…" \
  -F file=@coin.png
```

```json
{ "url": "https://…/coins/img/3f2a….webp", "kind": "image" }
```

For a banner, add `-F kind=banner` (cropped to 3:1, 1500 × 500). You can also send JSON: `{"url": "https://…"}` to have woop fetch it, or `{"data": "<base64>"}`.

You can skip this step and pass any `https` image URL in the launch: woop fetches and stores it for you.

## 2. Pick a pair

The pair is what the coin trades against, and what its holders get paid in. Only open pairs work:

```bash
curl https://usewoop.xyz/api/v1/pairs \
  -H "Authorization: Bearer woop_…"
```

```json
[{ "symbol": "SOL", "name": "Solana", "mint": "So111…112", "category": "Crypto", "logo": "https://…", "decimals": 9, "graduationRaise": 125.8 }]
```

Pass the pair's `symbol` or `mint`.

Check a ticker first if you like: `GET /api/v1/tickers/MOON` returns whether it's free. A ticker someone already has costs 1 SOL, paid to that coin's holders.

## 3. Build the launch

```bash
curl https://usewoop.xyz/api/v1/launches \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "8hyP…vMh6",
    "name": "Moon Cat",
    "symbol": "MCAT",
    "image": "https://…/coins/img/3f2a….webp",
    "pair": "SOL",
    "description": "The cat that went to the moon.",
    "banner": "https://…/coins/banner/9c1d….webp",
    "links": { "website": "https://mooncat.xyz", "x": "https://x.com/mooncat", "telegram": "https://t.me/mooncat" },
    "firstBuy": "0.5"
  }'
```

| Field | | |
|---|---|---|
| `wallet` | required | The creator's wallet. It signs and pays for the launch |
| `name` | required | 1–32 characters |
| `symbol` | required | The ticker: 2–10 letters or numbers |
| `image` | required | From `/uploads`, or any `https` image URL |
| `pair` | required | A pair's symbol or mint from `/pairs` |
| `description` | optional | Up to 280 characters |
| `banner` | optional | A 3:1 banner, from `/uploads` (`kind=banner`) or a URL |
| `links` | optional | `website`, `x`, `telegram` (https only) |
| `firstBuy` | optional | The creator's buy in the fair opening, in the pair token |
| `unlockDays` | optional | Days the creator's coins unlock over after graduation (default 10) |
| `cliffDays` | optional | Days after graduation before they start unlocking (default 0) |

```json
{
  "mint": "7xKX…",
  "transaction": "AQAAAA…",
  "lastValidBlockHeight": 312345678,
  "pair": { "symbol": "SOL", "mint": "So111…112" },
  "costSol": 0.0297,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

`mint` is the new coin's address. `costSol` is what the launch costs the creator in network fees and rent; a first buy is on top. The transaction is valid for about a minute.

## 4. Sign and send

The creator's wallet signs `transaction` (base64, a versioned transaction already signed by the new mint). Then:

```bash
curl https://usewoop.xyz/api/v1/transactions \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "transaction": "<signed base64>", "lastValidBlockHeight": 312345678 }'
```

```json
{ "kind": "launch", "signature": "5Jx…", "mint": "7xKX…", "url": "https://usewoop.xyz/coin/7xKX…" }
```

The coin is live. It's on woop's Pulse and Coins pages within seconds, and counts toward your key's launches.

## In code

```js
// Node, with @solana/web3.js and a wallet that can sign
import { VersionedTransaction } from '@solana/web3.js';

const api = (path, body) => fetch(`https://usewoop.xyz/api/v1${path}`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
}).then((r) => r.json());

const launch = await api('/launches', { wallet: wallet.publicKey.toBase58(), name: 'Moon Cat', symbol: 'MCAT', image, pair: 'SOL' });
const tx = VersionedTransaction.deserialize(Buffer.from(launch.transaction, 'base64'));
tx.sign([wallet]); // the mint's signature stays
const sent = await api('/transactions', { transaction: Buffer.from(tx.serialize()).toString('base64'), lastValidBlockHeight: launch.lastValidBlockHeight });
console.log(sent.url);
```

## What the coin gets

Everything a coin launched on woop gets: a fair opening, Fair Blocks, the Exit Queue, holders paid every hour, ticker protection, the creator's coins locked until graduation, and its own WAMM pool with liquidity locked for good. The creator earns from every trade. See [the woopcurve](https://usewoop.xyz/docs/woopcurve) and [creator fees](https://usewoop.xyz/docs/creators/creator-fees).

---

# Trade

Source: https://usewoop.xyz/docs/api/trading

Buy and sell woopcurve coins instantly or in a Fair Block.

`POST /api/v1/trades` builds a buy or a sell for a wallet and returns a quote and the transaction to sign.

```bash
curl https://usewoop.xyz/api/v1/trades \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "8hyP…vMh6", "mint": "7xKX…", "side": "buy", "amount": "0.25", "mode": "instant" }'
```

| Field | | |
|---|---|---|
| `wallet` | required | The trader's wallet |
| `mint` | required | The coin |
| `side` | required | `buy` or `sell` |
| `amount` | required | Buys: pair token to spend (fees included). Sells: coins to sell |
| `mode` | optional | `instant` (default) or `block` for a Fair Block order |
| `slippageBps` | optional | Instant trades: the most the price may move, in basis points |
| `payWith` | optional | `sol` to pay with SOL on a non-SOL pair (swapped in the same transaction) |
| `ref` | optional | A promoter wallet: it earns 0.25% of the trade |

```json
{
  "transaction": "AQAAAA…",
  "lastValidBlockHeight": 312345690,
  "side": "buy",
  "mode": "instant",
  "amountIn": "0.25",
  "expectedOut": "4580211.33",
  "minOut": "4534409.21",
  "priceImpactPct": 0.84,
  "fee": "0.00375",
  "exitQueue": { "coins": "1200000", "quote": "0.065", "dip": false, "discountPct": 0 },
  "block": null
}
```

Sign `transaction` with the trader's wallet and post it to `/api/v1/transactions`.

## Instant or Fair Block

- **Instant** fills now. A buy takes from the [Exit Queue](https://usewoop.xyz/docs/api/exit-queue) first (no price impact), then the curve. Instant sells cost more and take at most a fifth of a position at a time.
- **Fair Block** (`mode: "block"`) joins the open block. Every order in it settles together, at one price, a few seconds later, and is paid out automatically. Nobody can jump or sandwich it.

After graduation, trades go through the coin's WAMM pool.

## Earn on trades you bring

Pass your own wallet as `ref` and it earns 0.25% of every trade your app sends, paid in the pair token. See [share links](https://usewoop.xyz/docs/promoters/share-links).

---

# Exit Queue

Source: https://usewoop.xyz/docs/api/exit-queue

Queue a big sell so it fills into buys at the curve's price, never below a floor.

A big sell can wait in the Exit Queue instead of hitting the curve. Every instant buy fills from the queue first, at the curve's price and never below the seller's floor, so the chart doesn't drop. The seller is paid automatically as it fills.

## Queue a sell

```bash
curl https://usewoop.xyz/api/v1/exits \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "8hyP…vMh6", "mint": "7xKX…", "amount": "20000000", "floorPct": -5 }'
```

`amount` is in coins. `floorPct` is the lowest price you'll accept against the price now: `-5` means up to 5% below (the default). It returns `transaction` and `lastValidBlockHeight` to sign and send.

## See the queue

`GET /api/v1/coins/{mint}/queue?wallet=…` returns the orders waiting now (`orders`, each with its `slot`) and the queue's `history`: every order it has had (waiting, filled, partly filled or cancelled) with what each sold and got.

## Cancel

```bash
curl https://usewoop.xyz/api/v1/exits/cancel \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "8hyP…vMh6", "mint": "7xKX…", "slot": 0 }'
```

The unsold coins and anything the order has sold for go back to the wallet.

---

# Creator tools and refunds

Source: https://usewoop.xyz/docs/api/creators

Take unlocked coins, lock for longer, and refunds, through the API.

A coin's creator can do through the API everything they can on the coin page. Each one returns a [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction): the creator's wallet signs it, then you send it to `/api/v1/transactions`.

## How the creator's coins work

Everything the creator buys before graduation (their first buy in the fair opening included) is locked. After graduation it unlocks an equal part each day over `unlockDays` (10 by default), after `cliffDays` (0 by default). The creator can't sell on the curve.

See where a creator stands with `GET /api/v1/coins/{mint}/curve`: its `creator` object has `locked`, `claimed` and `claimable`, plus the lock's days.

## Take unlocked coins

```bash
curl https://usewoop.xyz/api/v1/creator/claim \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "<creator>", "mint": "7xKX…" }'
```

Sends whatever has unlocked so far to the creator's wallet.

## Lock for longer

```bash
curl https://usewoop.xyz/api/v1/creator/lock \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "<creator>", "mint": "7xKX…", "unlockDays": 30, "cliffDays": 7 }'
```

A lock can only grow: longer, never shorter. Holders see the new lock on the coin page.

## Creator fees

The creator earns on every trade, before and after graduation. Fees are paid out automatically about every 10 minutes, with nothing to claim. `GET /api/v1/coins/{mint}/curve` shows what's waiting (`creatorFeesOwed`) and the launch advance still owed (`advance`). See [creator fees](https://usewoop.xyz/docs/creators/creator-fees).

## Refunds

If a coin doesn't graduate within 7 days, it goes into refund mode and everyone gets back the same share of what they put in. woop's keeper pays every holder automatically. If you'd rather not wait for it:

```bash
curl https://usewoop.xyz/api/v1/refunds \
  -H "Authorization: Bearer woop_…" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "<holder>", "mint": "7xKX…" }'
```

`GET /api/v1/coins/{mint}/curve?wallet=<holder>` shows the wallet's refund under `mine.refund`.

## Holders get paid automatically

Holder payouts need nothing from you: every hour, woop sends each holder their share in the pair token and pays the network fee. Read them with `GET /api/v1/coins/{mint}/payouts`, and a wallet's earnings with `GET /api/v1/wallets/{wallet}/portfolio`.

---

# Read data

Source: https://usewoop.xyz/docs/api/reading-data

Coins, trades, holders, candles, curve state and the Exit Queue.

All reads are `GET` requests with your key.

## Coins

`GET /api/v1/coins?sort=active|new|graduated&limit=20&pair=SOL`

Coins on woop, most active first by default. `pair` filters by a pair's symbol or mint.

`GET /api/v1/coins/{mint}`

One coin: name, ticker, image, pair, price, market cap, liquidity, holders, 24h volume and move, how far along the curve it is, and what holding it has paid.

## Trades, holders, candles

| Endpoint | Returns |
|---|---|
| `/coins/{mint}/trades?limit=60` | The newest trades. Fair Block orders, Exit Queue fills and fair launch shares are tagged in `via` |
| `/coins/{mint}/holders` | The biggest holders: share, since when, what each bought, sold and earned, and their PnL |
| `/coins/{mint}/candles?tf=60` | Market-cap candles in USD. `tf` in seconds: 1, 5, 15, 30, 60, 300, 900, 1800, 3600 or 14400 |

## The curve

`GET /api/v1/coins/{mint}/curve?wallet=…`

The woopcurve's state: its status (opening, trading, graduated and so on), how much it has raised and needs to graduate, market caps, the open Fair Block, the fees and the creator's lock. With `wallet`, that wallet's position too.

## The Exit Queue

`GET /api/v1/coins/{mint}/queue?wallet=…`: see [Exit Queue](https://usewoop.xyz/docs/api/exit-queue).

## Positions, payouts, events, signals

| Endpoint | Returns |
|---|---|
| `/coins/{mint}/positions/{wallet}` | One wallet in the coin: holding, paid, got, profit or loss ([Position](https://usewoop.xyz/docs/api/schemas#position)) |
| `/coins/{mint}/payouts` | The hourly payouts to holders ([Payout](https://usewoop.xyz/docs/api/schemas#payout)) |
| `/coins/{mint}/events` | Holder payouts, promoter fees, Fair Blocks, Exit Queue fills and creator fees, oldest first ([Event](https://usewoop.xyz/docs/api/schemas#event)) |
| `/coins/{mint}/signals` | Rug signals: dev-linked wallets, snipers, bundled buys, who funded the creator ([Signals](https://usewoop.xyz/docs/api/schemas#signals)) |

## Wallets

`GET /api/v1/wallets/{wallet}/portfolio`

Every woop coin the wallet holds or earned from, with what each is worth and has paid it, and totals ([Portfolio](https://usewoop.xyz/docs/api/schemas#portfolio)).

Every field of every response is on [Objects](https://usewoop.xyz/docs/api/schemas).

## Pairs, tickers, you

| Endpoint | Returns |
|---|---|
| `/pairs` | Pairs a coin can launch on |
| `/tickers/{symbol}` | Whether a ticker is free (a taken one costs 1 SOL, paid to its holders) |
| `/me` | Your key's wallet, its usage, and the coins it launched |
| `/launches` | The coins your key's wallet launched through the API |

---

# Errors and limits

Source: https://usewoop.xyz/docs/api/errors

Error responses, rate limits and what to do about them.

## Errors

A failed request returns a 4xx or 5xx status and:

```json
{ "error": { "code": "pair_not_open", "message": "`DOGE` isn't a pair you can launch on. GET /api/v1/pairs lists them." } }
```

The `message` is written so you can show it to a user as it is.

| Status | `code` | Meaning |
|---|---|---|
| 400 | `missing_field`, `bad_field`, `bad_json`, `bad_image` | Something in the request is missing or wrong |
| 401 | `missing_key`, `invalid_key` | No key, or a key that was rotated |
| 404 | `not_found` | No coin at that address |
| 422 | `rejected` | The launch or trade can't go through as asked: not enough SOL, a slippage limit, a curve that's closed |
| 422 | `pair_not_open`, `not_curve`, `expired` | The pair isn't open; the coin isn't on the woopcurve; the transaction expired before it was sent |
| 429 | `rate_limited` | Too many requests. Wait a moment |
| 500 | `server_error` | Our side. Try again |

## Limits

| Limit | Per key |
|---|---|
| Requests | 600 a minute |

Launches have no limit of their own: each one is a request like any other.

Every response carries `x-ratelimit-remaining`: the requests left this minute.

## Transactions expire

A built transaction is valid for about a minute (until `lastValidBlockHeight`). If it expires, build it again.

---

# Endpoint reference

Source: https://usewoop.xyz/docs/api/reference

Every v1 endpoint, with its parameters, body and response.

Base URL `https://usewoop.xyz/api/v1`. Send `Authorization: Bearer woop_…` with every request. The machine-readable schema (OpenAPI 3.1) is at [`/api/v1/openapi.json`](https://usewoop.xyz/api/v1/openapi.json): load it into Postman, Insomnia or a client generator.

Every endpoint can also answer with an [Error](https://usewoop.xyz/docs/api/schemas#error): see [errors and limits](https://usewoop.xyz/docs/api/errors).

| Method | Path | Does |
|---|---|---|
| `POST` | [`/uploads`](#post-uploads) | Store an image |
| `POST` | [`/launches`](#post-launches) | Build a launch |
| `GET` | [`/launches`](#get-launches) | Your launches |
| `GET` | [`/pairs`](#get-pairs) | Pairs open for launches |
| `GET` | [`/tickers/{symbol}`](#get-tickerssymbol) | Check a ticker |
| `POST` | [`/trades`](#post-trades) | Build a buy or sell |
| `POST` | [`/exits`](#post-exits) | Queue a sell |
| `POST` | [`/exits/cancel`](#post-exitscancel) | Cancel a queued sell |
| `POST` | [`/creator/claim`](#post-creatorclaim) | Take unlocked coins |
| `POST` | [`/creator/lock`](#post-creatorlock) | Lock for longer |
| `POST` | [`/refunds`](#post-refunds) | Take a refund |
| `POST` | [`/transactions`](#post-transactions) | Send a signed transaction |
| `GET` | [`/coins`](#get-coins) | List coins |
| `GET` | [`/coins/{mint}`](#get-coinsmint) | One coin |
| `GET` | [`/coins/{mint}/trades`](#get-coinsminttrades) | Its trades |
| `GET` | [`/coins/{mint}/holders`](#get-coinsmintholders) | Its holders |
| `GET` | [`/coins/{mint}/candles`](#get-coinsmintcandles) | Its candles |
| `GET` | [`/coins/{mint}/curve`](#get-coinsmintcurve) | Its woopcurve state |
| `GET` | [`/coins/{mint}/queue`](#get-coinsmintqueue) | Its Exit Queue |
| `GET` | [`/coins/{mint}/positions/{wallet}`](#get-coinsmintpositionswallet) | A wallet's position |
| `GET` | [`/coins/{mint}/payouts`](#get-coinsmintpayouts) | Its payouts to holders |
| `GET` | [`/coins/{mint}/events`](#get-coinsmintevents) | Its events |
| `GET` | [`/coins/{mint}/signals`](#get-coinsmintsignals) | Its rug signals |
| `GET` | [`/wallets/{wallet}/portfolio`](#get-walletswalletportfolio) | A wallet's portfolio |
| `GET` | [`/me`](#get-me) | Your key |

## Launch

### POST /uploads

Store an image. A coin image (cropped square) or a 3:1 banner, as WebP on woop's CDN. Send multipart `file` (and `kind`), or JSON.

**Body:** [UploadJson](https://usewoop.xyz/docs/api/schemas#uploadjson)

| Field | Type | Description |  |
|---|---|---|---|
| `url` | string | An https image for woop to fetch | optional |
| `data` | string | The image as base64 (a data: URL works) | optional |
| `kind` | image\|banner | Default image | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/uploads" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -F file=@moon-cat.png \
  -F kind=image
```

```js
const form = new FormData();
form.append('file', file); // a File or Blob
form.append('kind', 'image');

const res = await fetch('https://usewoop.xyz/api/v1/uploads', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
  body: form,
});
const { url } = await res.json();
```

**Returns:** [Upload](https://usewoop.xyz/docs/api/schemas#upload)

```json
{
  "url": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "kind": "image"
}
```

### POST /launches

Build a launch. A new coin on the woopcurve. Name, ticker, image and pair are required. The creator signs the result and sends it to /transactions; the coin then shows on woop like any other.

**Body:** [LaunchRequest](https://usewoop.xyz/docs/api/schemas#launchrequest)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The creator. Signs and pays for the launch, and is credited as its creator |  |
| `name` | string | 1–32 characters |  |
| `symbol` | string | The ticker: 2–10 letters or numbers |  |
| `image` | string | From POST /uploads, or any https image URL (woop stores it) |  |
| `pair` | string | A pair's symbol or mint from GET /pairs |  |
| `description` | string | Up to 280 characters | optional |
| `banner` | string | A 3:1 banner: from POST /uploads (kind banner) or an https URL | optional |
| `links` | [Links](https://usewoop.xyz/docs/api/schemas#links) | The coin's website and socials | optional |
| `firstBuy` | string | The creator's buy in the fair opening, in the pair token (e.g. "0.5") | optional |
| `unlockDays` | integer | Days the creator's coins unlock over after graduation (default 10) | optional |
| `cliffDays` | integer | Days after graduation before they start unlocking (default 0) | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/launches" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","name":"Moon Cat","symbol":"MCAT","image":"https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp","pair":"SOL","description":"The cat that went to the moon.","links":{"website":"https://mooncat.xyz","x":"https://x.com/mooncat"},"firstBuy":"0.5"}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/launches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "name": "Moon Cat",
    "symbol": "MCAT",
    "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
    "pair": "SOL",
    "description": "The cat that went to the moon.",
    "links": {
      "website": "https://mooncat.xyz",
      "x": "https://x.com/mooncat"
    },
    "firstBuy": "0.5"
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const launchResult = await res.json();
// next: sign launchResult.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [LaunchResult](https://usewoop.xyz/docs/api/schemas#launchresult)

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "metadataUri": "https://zync-pad.b-cdn.net/coins/5eCpSHzTKsiafptauyG2vfDZhSdvMR4dz7jgvMX7Paop.json",
  "pair": {
    "symbol": "SOL",
    "mint": "So11111111111111111111111111111111111111112"
  },
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "banner": "https://zync-pad.b-cdn.net/coins/banner/0c1d2e3f4a5b6c7d8e9f0a1b.webp",
  "costSol": 0.015,
  "firstBuy": {
    "amount": "0.5",
    "coins": "in the fair opening"
  },
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### GET /launches

Your launches. Coins your key's wallet launched through the API.

**Request**

```bash
curl "https://usewoop.xyz/api/v1/launches" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/launches', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const apiLaunchs = await res.json();
```

**Returns:** [ApiLaunch](https://usewoop.xyz/docs/api/schemas#apilaunch)[]

```json
[
  {
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "name": "Moon Cat",
    "symbol": "MCAT",
    "launchedAt": "2026-11-01T14:58:36.000Z",
    "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
  }
]
```

### GET /pairs

Pairs open for launches. The pairs a coin can launch on right now.

**Request**

```bash
curl "https://usewoop.xyz/api/v1/pairs" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/pairs', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const pairs = await res.json();
```

**Returns:** [Pair](https://usewoop.xyz/docs/api/schemas#pair)[]

```json
[
  {
    "symbol": "SOL",
    "name": "Solana",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "category": "Crypto",
    "logo": "https://zync-pad.b-cdn.net/pairs/So11111111111111111111111111111111111111112.webp",
    "decimals": 9,
    "graduationRaise": 125.8
  }
]
```

### GET /tickers/{symbol}

Check a ticker. Whether a ticker is free. A taken one costs 1 SOL, paid to that coin's holders.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `symbol` | path | string | 2–10 letters or numbers | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/tickers/MCAT" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/tickers/MCAT', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const ticker = await res.json();
```

**Returns:** [Ticker](https://usewoop.xyz/docs/api/schemas#ticker)

```json
{
  "symbol": "MCAT",
  "available": false,
  "takenBy": {
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "name": "Moon Cat"
  },
  "copyFeeSol": 1
}
```

## Trade

### POST /trades

Build a buy or sell. Instant (the Exit Queue first, then the curve or pool) or a Fair Block order (settles with the block at one price).

**Body:** [TradeRequest](https://usewoop.xyz/docs/api/schemas#traderequest)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The trader |  |
| `mint` | string | The coin |  |
| `side` | buy\|sell | Buy or sell |  |
| `amount` | string | Buys: pair token to spend, fees included. Sells: coins to sell |  |
| `mode` | instant\|block | instant (default) fills now; block joins the open Fair Block | optional |
| `slippageBps` | integer | Instant trades: the most the price may move, in basis points | optional |
| `payWith` | pair\|sol | sol pays with SOL on a non-SOL pair, swapped in the same transaction (mainnet) | optional |
| `ref` | string | A promoter wallet: it earns 0.25% of the trade | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/trades" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp","side":"buy","amount":"0.25","mode":"instant","slippageBps":300}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/trades', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "side": "buy",
    "amount": "0.25",
    "mode": "instant",
    "slippageBps": 300
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const tradeResult = await res.json();
// next: sign tradeResult.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [TradeResult](https://usewoop.xyz/docs/api/schemas#traderesult)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "side": "buy",
  "mode": "instant",
  "amountIn": "0.25",
  "expectedOut": "4580211.33",
  "minOut": "4442804.99",
  "priceImpactPct": 0.84,
  "fee": "0.00375",
  "exitQueue": {
    "coins": "1200000",
    "quote": "0.065",
    "dip": false,
    "discountPct": 0
  },
  "block": null,
  "swap": null,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

## Exit Queue

### POST /exits

Queue a sell. Coins wait in the Exit Queue and fill into instant buys at the curve's price, never below the floor. The seller is paid automatically.

**Body:** [ExitPlaceRequest](https://usewoop.xyz/docs/api/schemas#exitplacerequest)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The seller |  |
| `mint` | string | The coin |  |
| `amount` | string | Coins to queue |  |
| `floorPct` | number | The lowest price accepted against now, −50 to 900 (default −5: up to 5% below) | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/exits" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp","amount":"20000000","floorPct":-5}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/exits', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "amount": "20000000",
    "floorPct": -5
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const builtTransaction = await res.json();
// next: sign builtTransaction.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### POST /exits/cancel

Cancel a queued sell. Unsold coins and what the order sold for go back to the seller.

**Body:** [ExitCancelRequest](https://usewoop.xyz/docs/api/schemas#exitcancelrequest)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The seller |  |
| `mint` | string | The coin |  |
| `slot` | integer | The order's slot, from GET /coins/{mint}/queue |  |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/exits/cancel" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp","slot":0}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/exits/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "slot": 0
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const builtTransaction = await res.json();
// next: sign builtTransaction.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

## Creator

### POST /creator/claim

Take unlocked coins. After graduation the creator's coins unlock day by day; this sends what has unlocked so far to the creator.

**Body:** [WalletCoin](https://usewoop.xyz/docs/api/schemas#walletcoin)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The wallet that signs |  |
| `mint` | string | The coin |  |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/creator/claim" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/creator/claim', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const builtTransaction = await res.json();
// next: sign builtTransaction.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### POST /creator/lock

Lock for longer. The creator extends their lock. It can only grow.

**Body:** [CreatorLockRequest](https://usewoop.xyz/docs/api/schemas#creatorlockrequest)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The coin's creator |  |
| `mint` | string | The coin |  |
| `unlockDays` | integer | Days to unlock over, 1–3650 |  |
| `cliffDays` | integer | Days before unlocking starts, 0–3650 (default 0) | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/creator/lock" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp","unlockDays":30,"cliffDays":7}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/creator/lock', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "unlockDays": 30,
    "cliffDays": 7
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const builtTransaction = await res.json();
// next: sign builtTransaction.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### POST /refunds

Take a refund. A coin that didn't graduate in time refunds everyone the same share of what they put in. The keeper pays everyone automatically; this is the do-it-yourself way.

**Body:** [WalletCoin](https://usewoop.xyz/docs/api/schemas#walletcoin)

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The wallet that signs |  |
| `mint` | string | The coin |  |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/refunds" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6","mint":"6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/refunds', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const builtTransaction = await res.json();
// next: sign builtTransaction.transaction with the wallet, then POST it to /api/v1/transactions
```

**Returns:** [BuiltTransaction](https://usewoop.xyz/docs/api/schemas#builttransaction)

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

## Transactions

### POST /transactions

Send a signed transaction. Send any signed transaction from a build endpoint. Waits until it confirms. A launch built here is credited to your key's wallet.

**Body:** [SendRequest](https://usewoop.xyz/docs/api/schemas#sendrequest)

| Field | Type | Description |  |
|---|---|---|---|
| `transaction` | string | Base64, signed |  |
| `lastValidBlockHeight` | integer | From the build response | optional |

**Request**

```bash
curl -X POST "https://usewoop.xyz/api/v1/transactions" \
  -H "Authorization: Bearer $WOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction":"AQAB…signed base64…","lastValidBlockHeight":312345678}'
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WOOP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transaction": "AQAB…signed base64…",
    "lastValidBlockHeight": 312345678
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const sendResult = await res.json();
```

**Returns:** [SendResult](https://usewoop.xyz/docs/api/schemas#sendresult)

```json
{
  "kind": "launch",
  "signature": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
}
```

## Coins

### GET /coins

List coins. Coins on woop.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `sort` | query | active\|new\|graduated | active (default): last traded first; new: newest first; graduated | optional |
| `limit` | query | integer | 1–100, default 20 | optional |
| `pair` | query | string | Only coins on this pair (symbol or mint) | optional |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins?sort=new&limit=20" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins?sort=new&limit=20', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const coinSummarys = await res.json();
```

**Returns:** [CoinSummary](https://usewoop.xyz/docs/api/schemas#coinsummary)[]

```json
[
  {
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "name": "Moon Cat",
    "symbol": "MCAT",
    "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
    "quoteMint": "So11111111111111111111111111111111111111112",
    "mcUsd": 9640.5,
    "priceQuote": 6.34e-8,
    "holders": 128,
    "graduated": true,
    "lastTradeAt": "2026-11-01T15:20:11.000Z",
    "createdAt": "2026-11-01T14:58:36.000Z"
  }
]
```

### GET /coins/{mint}

One coin.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const coin = await res.json();
```

**Returns:** [Coin](https://usewoop.xyz/docs/api/schemas#coin)

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "name": "Moon Cat",
  "symbol": "MCAT",
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "quoteMint": "So11111111111111111111111111111111111111112",
  "mcUsd": 9640.5,
  "priceQuote": 6.34e-8,
  "holders": 128,
  "graduated": true,
  "lastTradeAt": "2026-11-01T15:20:11.000Z",
  "createdAt": "2026-11-01T14:58:36.000Z",
  "curve": true,
  "banner": null,
  "creator": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "network": "mainnet",
  "quoteUsd": 152.1,
  "priceUsd": 0.0000096,
  "liquidityUsd": 3820.4,
  "paidToHoldersUsd": 41.27,
  "paidToHoldersQuote": 0.2713,
  "curvePct": 7.7,
  "top10Pct": 18.4,
  "devPct": 1.9,
  "volume24hUsd": 15230,
  "change24hPct": 34.2,
  "trades": 412,
  "fairSale": null
}
```

### GET /coins/{mint}/trades

Its trades. Newest first. Fair Block orders, Exit Queue fills and fair launch shares are tagged in `via`.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |
| `limit` | query | integer | 1–200, default 60 | optional |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/trades?limit=60" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/trades?limit=60', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const trades = await res.json();
```

**Returns:** [Trade](https://usewoop.xyz/docs/api/schemas#trade)[]

```json
[
  {
    "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
    "signature": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx",
    "side": "buy",
    "trader": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "quote": 0.25,
    "amount": 4580211.33,
    "usd": 38.02,
    "mcUsd": 9640.5,
    "time": "2026-11-01T14:58:36.000Z",
    "via": "block"
  }
]
```

### GET /coins/{mint}/holders

Its holders. The biggest 100, with what each bought, sold and earned.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/holders" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/holders', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const holders = await res.json();
```

**Returns:** [Holder](https://usewoop.xyz/docs/api/schemas#holder)[]

```json
[
  {
    "address": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
    "pct": 0.46,
    "since": "2026-11-01T14:58:36.000Z",
    "amount": 4580211.33,
    "earnedQuote": 0.0031,
    "earnedUsd": 0.47,
    "boughtAmount": 6000000,
    "soldAmount": 1420000,
    "boughtQuote": 0.2,
    "soldQuote": 0.1,
    "valueQuote": 0.2903,
    "pnlQuote": 0.1903,
    "boughtUsd": 30.42,
    "soldUsd": 15.21,
    "valueUsd": 44.15,
    "pnlUsd": 28.94
  }
]
```

### GET /coins/{mint}/candles

Its candles. Market-cap candles in USD.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |
| `tf` | query | integer | Seconds per candle: 1, 5, 15, 30, 60 (default), 300, 900, 1800, 3600 or 14400 | optional |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/candles?tf=60" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/candles?tf=60', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const candles = await res.json();
```

**Returns:** [Candle](https://usewoop.xyz/docs/api/schemas#candle)[]

```json
[
  {
    "time": 3,
    "open": 9600,
    "high": 9800,
    "low": 9500,
    "close": 9640,
    "volume": 512.3
  }
]
```

### GET /coins/{mint}/curve

Its woopcurve state. Progress, graduation, the open Fair Block, fees and the creator's lock. With `wallet`, that wallet's order, Exit Queue orders, instant-sell allowance and refund.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |
| `wallet` | query | string | A wallet: adds its side | optional |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/curve?wallet=8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/curve?wallet=8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const curve = await res.json();
```

**Returns:** [Curve](https://usewoop.xyz/docs/api/schemas#curve)

```json
{
  "status": "trading",
  "quoteDecimals": 9,
  "raised": 9.68,
  "target": 125.8,
  "soldPct": 7.1,
  "mcap": {
    "start": 33,
    "now": 63.4,
    "graduation": 328.8
  },
  "graduatedAt": null,
  "pool": null,
  "openingEndsAt": null,
  "blockClosesAt": null,
  "refundAt": "2026-11-01T14:58:36.000Z",
  "advance": {
    "amount": 4580211.33,
    "repaid": 0.06,
    "owed": 0.94
  },
  "creator": {
    "locked": 18791167.7,
    "vest": 0,
    "claimed": 0,
    "claimable": 0,
    "unlockDays": 10,
    "cliffDays": 0,
    "graduatedAt": null
  },
  "creatorFeesOwed": 0.0042,
  "fees": {
    "trade": 1.5,
    "instant": 10,
    "exit": 1,
    "pool": 1.5,
    "tierHalf": true,
    "split": {
      "trade": [
        0.6,
        0.5,
        0.4
      ],
      "instant": [
        0.5,
        0.25,
        0.25
      ],
      "exit": [
        0.5,
        0.25,
        0.25
      ],
      "pool": [
        0.6,
        0.5,
        0.4
      ]
    }
  },
  "mine": {
    "order": null,
    "exits": [
      {
        "slot": 0,
        "left": 4000000,
        "owed": 0.94,
        "floorPct": -5
      }
    ],
    "instantMax": 916042.2,
    "instantNextAt": null,
    "refund": null
  }
}
```

### GET /coins/{mint}/queue

Its Exit Queue. Orders waiting now and every order before them.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |
| `wallet` | query | string | A wallet: adds its side | optional |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/queue?wallet=8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/queue?wallet=8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const queue = await res.json();
```

**Returns:** [Queue](https://usewoop.xyz/docs/api/schemas#queue)

```json
{
  "spot": 6.34e-8,
  "quoteDecimals": 9,
  "orders": [
    {
      "slot": 0,
      "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
      "seller": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
      "remaining": 12000000,
      "floor": 6.02e-8,
      "floorPct": -5,
      "proceeds": 0.31,
      "mine": true
    }
  ],
  "totalQueued": 12000000,
  "graduated": true,
  "feePct": 1,
  "tierFeePct": 0.5,
  "tier": true,
  "history": [
    {
      "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
      "seller": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
      "mine": true,
      "amount": 8000000,
      "filled": 8000000,
      "received": 0.49,
      "floor": 6.02e-8,
      "status": "filled",
      "placedAt": "2026-11-01T15:02:10.000Z",
      "closedAt": null,
      "slot": null
    }
  ]
}
```

### GET /coins/{mint}/positions/{wallet}

A wallet's position. What the wallet holds, paid and got, and its profit or loss.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |
| `wallet` | path | string | The wallet | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/positions/8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/positions/8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const position = await res.json();
```

**Returns:** [Position](https://usewoop.xyz/docs/api/schemas#position)

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "amount": 4580211.33,
  "pct": 0.46,
  "quoteSymbolMint": "So11111111111111111111111111111111111111112",
  "valueQuote": 0.2903,
  "valueUsd": 44.15,
  "paidQuote": 0.2,
  "receivedQuote": 0.1,
  "pnlQuote": 0.1903,
  "pnlUsd": 28.94,
  "trades": 412,
  "boughtAmount": 6000000,
  "soldAmount": 1420000,
  "since": "2026-11-01T14:58:36.000Z",
  "quoteUsd": 152.1
}
```

### GET /coins/{mint}/payouts

Its payouts to holders. Holders are paid every hour, automatically, in the pair token.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/payouts" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/payouts', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const payouts = await res.json();
```

**Returns:** [Payout](https://usewoop.xyz/docs/api/schemas#payout)[]

```json
[
  {
    "epoch": 37,
    "rewardMint": "So11111111111111111111111111111111111111112",
    "amount": 0.0271,
    "amountUsd": 4.12,
    "holders": 128,
    "postedAt": "2026-11-01T15:00:00.000Z"
  }
]
```

### GET /coins/{mint}/events

Its events. Holder payouts, promoter fees, Fair Blocks, Exit Queue fills and creator fees, oldest first (the chart's markers).

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/events" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/events', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const events = await res.json();
```

**Returns:** [Event](https://usewoop.xyz/docs/api/schemas#event)[]

```json
[
  {
    "time": 3,
    "kind": "fairblock",
    "usd": 94.9,
    "n": 14
  }
]
```

### GET /coins/{mint}/signals

Its rug signals. Dev-linked wallets, snipers, bundled buys and who funded the creator.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `mint` | path | string | The coin's address | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/signals" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/coins/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp/signals', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const signals = await res.json();
```

**Returns:** [Signals](https://usewoop.xyz/docs/api/schemas#signals)

```json
{
  "devFunder": "3Qx9vLm2TnB8rJ5cWzXy7kP4sF1gH6dA9eN0bRtUoVi",
  "devFundedByExchange": true,
  "linked": {
    "wallets": [],
    "pct": 0
  },
  "snipers": {
    "wallets": [],
    "pct": 0
  },
  "bundled": {
    "wallets": [],
    "pct": 0
  },
  "lock": null,
  "checked": 40,
  "holders": 128
}
```

## Wallets

### GET /wallets/{wallet}/portfolio

A wallet's portfolio. Every woop coin the wallet holds or earned from, with totals.

| Parameter | In | Type | Description |  |
|---|---|---|---|---|
| `wallet` | path | string | The wallet | required |

**Request**

```bash
curl "https://usewoop.xyz/api/v1/wallets/8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6/portfolio" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/wallets/8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6/portfolio', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const portfolio = await res.json();
```

**Returns:** [Portfolio](https://usewoop.xyz/docs/api/schemas#portfolio)

```json
{
  "holdings": [
    {
      "coin": {
        "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
        "name": "Moon Cat",
        "symbol": "MCAT",
        "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
        "quoteMint": "So11111111111111111111111111111111111111112",
        "mcUsd": 9640.5,
        "priceQuote": 6.34e-8,
        "holders": 128,
        "graduated": true,
        "lastTradeAt": "2026-11-01T15:20:11.000Z",
        "createdAt": "2026-11-01T14:58:36.000Z",
        "curve": true,
        "banner": null,
        "creator": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
        "network": "mainnet",
        "quoteUsd": 152.1,
        "priceUsd": 0.0000096,
        "liquidityUsd": 3820.4,
        "paidToHoldersUsd": 41.27,
        "paidToHoldersQuote": 0.2713,
        "curvePct": 7.7,
        "top10Pct": 18.4,
        "devPct": 1.9,
        "volume24hUsd": 15230,
        "change24hPct": 34.2,
        "trades": 412,
        "fairSale": null
      },
      "amount": 4580211.33,
      "pct": 0.46,
      "valueUsd": 44.15,
      "since": "2026-11-01T14:58:36.000Z",
      "earnedQuote": 0.0031,
      "earnedUsd": 0.47,
      "claimable": [],
      "claimableUsd": 0
    }
  ],
  "totals": {
    "valueUsd": 44.15,
    "earnedUsd": 0.47,
    "claimableUsd": 0,
    "claimableCount": 0,
    "coins": 3
  }
}
```

## Account

### GET /me

Your key. Your key's wallet, its usage and the coins it launched.

**Request**

```bash
curl "https://usewoop.xyz/api/v1/me" \
  -H "Authorization: Bearer $WOOP_API_KEY"
```

```js
const res = await fetch('https://usewoop.xyz/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.WOOP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const me = await res.json();
```

**Returns:** [Me](https://usewoop.xyz/docs/api/schemas#me)

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "key": {
    "prefix": "woop_AKPH67r",
    "createdAt": "2026-11-01T14:58:36.000Z",
    "lastUsedAt": "2026-11-01T14:58:36.000Z",
    "requests": 1840
  },
  "launches": [
    {
      "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
      "name": "Moon Cat",
      "symbol": "MCAT",
      "launchedAt": "2026-11-01T14:58:36.000Z",
      "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
    }
  ]
}
```

---

# Objects

Source: https://usewoop.xyz/docs/api/schemas

Every object the API sends and takes, field by field.

Amounts are in whole units (SOL, not lamports; coins, not raw units) unless a field says otherwise. Times are ISO 8601 strings, or Unix seconds where the type is an integer. A type "or null" is always present but can be null; an optional field can be left out.

## Requests

### LaunchRequest

A new coin. The same form as woop's launch page.

```ts
type LaunchRequest = {
  wallet: string; // The creator. Signs and pays for the launch, and is credited as its creator
  name: string; // 1–32 characters
  symbol: string; // The ticker: 2–10 letters or numbers
  image: string; // From POST /uploads, or any https image URL (woop stores it)
  pair: string; // A pair's symbol or mint from GET /pairs
  description?: string; // Up to 280 characters
  banner?: string; // A 3:1 banner: from POST /uploads (kind banner) or an https URL
  links?: Links; // The coin's website and socials
  firstBuy?: string; // The creator's buy in the fair opening, in the pair token (e.g. "0.5")
  unlockDays?: number; // Days the creator's coins unlock over after graduation (default 10)
  cliffDays?: number; // Days after graduation before they start unlocking (default 0)
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The creator. Signs and pays for the launch, and is credited as its creator |  |
| `name` | string | 1–32 characters |  |
| `symbol` | string | The ticker: 2–10 letters or numbers |  |
| `image` | string | From POST /uploads, or any https image URL (woop stores it) |  |
| `pair` | string | A pair's symbol or mint from GET /pairs |  |
| `description` | string | Up to 280 characters | optional |
| `banner` | string | A 3:1 banner: from POST /uploads (kind banner) or an https URL | optional |
| `links` | [Links](https://usewoop.xyz/docs/api/schemas#links) | The coin's website and socials | optional |
| `firstBuy` | string | The creator's buy in the fair opening, in the pair token (e.g. "0.5") | optional |
| `unlockDays` | integer | Days the creator's coins unlock over after graduation (default 10) | optional |
| `cliffDays` | integer | Days after graduation before they start unlocking (default 0) | optional |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "name": "Moon Cat",
  "symbol": "MCAT",
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "pair": "SOL",
  "description": "The cat that went to the moon.",
  "links": {
    "website": "https://mooncat.xyz",
    "x": "https://x.com/mooncat"
  },
  "firstBuy": "0.5"
}
```

### Links

Inside `LaunchRequest`. https only.

```ts
type Links = {
  website?: string; // Website
  x?: string; // X profile
  telegram?: string; // Telegram
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `website` | string | Website | optional |
| `x` | string | X profile | optional |
| `telegram` | string | Telegram | optional |

### TradeRequest

A buy or a sell.

```ts
type TradeRequest = {
  wallet: string; // The trader
  mint: string; // The coin
  side: 'buy' | 'sell'; // Buy or sell
  amount: string; // Buys: pair token to spend, fees included. Sells: coins to sell
  mode?: 'instant' | 'block'; // instant (default) fills now; block joins the open Fair Block
  slippageBps?: number; // Instant trades: the most the price may move, in basis points
  payWith?: 'pair' | 'sol'; // sol pays with SOL on a non-SOL pair, swapped in the same transaction (mainnet)
  ref?: string; // A promoter wallet: it earns 0.25% of the trade
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The trader |  |
| `mint` | string | The coin |  |
| `side` | buy\|sell | Buy or sell |  |
| `amount` | string | Buys: pair token to spend, fees included. Sells: coins to sell |  |
| `mode` | instant\|block | instant (default) fills now; block joins the open Fair Block | optional |
| `slippageBps` | integer | Instant trades: the most the price may move, in basis points | optional |
| `payWith` | pair\|sol | sol pays with SOL on a non-SOL pair, swapped in the same transaction (mainnet) | optional |
| `ref` | string | A promoter wallet: it earns 0.25% of the trade | optional |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "side": "buy",
  "amount": "0.25",
  "mode": "instant",
  "slippageBps": 300
}
```

### ExitPlaceRequest

A sell to queue.

```ts
type ExitPlaceRequest = {
  wallet: string; // The seller
  mint: string; // The coin
  amount: string; // Coins to queue
  floorPct?: number; // The lowest price accepted against now, −50 to 900 (default −5: up to 5% below)
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The seller |  |
| `mint` | string | The coin |  |
| `amount` | string | Coins to queue |  |
| `floorPct` | number | The lowest price accepted against now, −50 to 900 (default −5: up to 5% below) | optional |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "amount": "20000000",
  "floorPct": -5
}
```

### ExitCancelRequest

An Exit Queue order to take down.

```ts
type ExitCancelRequest = {
  wallet: string; // The seller
  mint: string; // The coin
  slot: number; // The order's slot, from GET /coins/{mint}/queue
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The seller |  |
| `mint` | string | The coin |  |
| `slot` | integer | The order's slot, from GET /coins/{mint}/queue |  |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "slot": 0
}
```

### WalletCoin

A wallet and a coin.

```ts
type WalletCoin = {
  wallet: string; // The wallet that signs
  mint: string; // The coin
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The wallet that signs |  |
| `mint` | string | The coin |  |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
}
```

### CreatorLockRequest

A longer creator lock. A lock can only grow.

```ts
type CreatorLockRequest = {
  wallet: string; // The coin's creator
  mint: string; // The coin
  unlockDays: number; // Days to unlock over, 1–3650
  cliffDays?: number; // Days before unlocking starts, 0–3650 (default 0)
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The coin's creator |  |
| `mint` | string | The coin |  |
| `unlockDays` | integer | Days to unlock over, 1–3650 |  |
| `cliffDays` | integer | Days before unlocking starts, 0–3650 (default 0) | optional |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "unlockDays": 30,
  "cliffDays": 7
}
```

### SendRequest

A signed transaction from any build endpoint.

```ts
type SendRequest = {
  transaction: string; // Base64, signed
  lastValidBlockHeight?: number; // From the build response
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `transaction` | string | Base64, signed |  |
| `lastValidBlockHeight` | integer | From the build response | optional |

**Example**

```json
{
  "transaction": "AQAB…signed base64…",
  "lastValidBlockHeight": 312345678
}
```

### UploadJson

The JSON body of an upload (or send multipart `file` and `kind`).

```ts
type UploadJson = {
  url?: string; // An https image for woop to fetch
  data?: string; // The image as base64 (a data: URL works)
  kind?: 'image' | 'banner'; // Default image
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `url` | string | An https image for woop to fetch | optional |
| `data` | string | The image as base64 (a data: URL works) | optional |
| `kind` | image\|banner | Default image | optional |

**Example**

```json
{
  "url": "https://example.com/moon-cat.png",
  "kind": "image"
}
```

## Build and send

### BuiltTransaction

Every endpoint that builds something returns this: sign `transaction` with the request's `wallet`, then send it.

```ts
type BuiltTransaction = {
  transaction: string; // A base64 versioned transaction, unsigned by the wallet (a launch is already signed by its new mint)
  lastValidBlockHeight: number; // It expires after this block height (about a minute)
  next: string; // What to do with it
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `transaction` | string | A base64 versioned transaction, unsigned by the wallet (a launch is already signed by its new mint) |  |
| `lastValidBlockHeight` | integer | It expires after this block height (about a minute) |  |
| `next` | string | What to do with it |  |

**Example**

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### LaunchResult

A launch ready to sign.

```ts
type LaunchResult = {
  mint: string; // The new coin's address
  transaction: string; // Base64, already signed by the new mint: the creator signs it too
  lastValidBlockHeight: number; // It expires after this
  metadataUri: string; // The coin's metadata on woop's CDN
  pair: PairRef; // The pair it launches on
  image: string; // The stored image
  banner: string | null; // The stored banner
  costSol: number; // Network fees and rent the launch costs the creator; a first buy is on top
  firstBuy: FirstBuy | null; // The first buy, if any
  next: string; // What to do with it
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `mint` | string | The new coin's address |  |
| `transaction` | string | Base64, already signed by the new mint: the creator signs it too |  |
| `lastValidBlockHeight` | integer | It expires after this |  |
| `metadataUri` | string | The coin's metadata on woop's CDN |  |
| `pair` | [PairRef](https://usewoop.xyz/docs/api/schemas#pairref) | The pair it launches on |  |
| `image` | string | The stored image |  |
| `banner` | string or null | The stored banner |  |
| `costSol` | number | Network fees and rent the launch costs the creator; a first buy is on top |  |
| `firstBuy` | [FirstBuy](https://usewoop.xyz/docs/api/schemas#firstbuy) or null | The first buy, if any |  |
| `next` | string | What to do with it |  |

**Example**

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "metadataUri": "https://zync-pad.b-cdn.net/coins/5eCpSHzTKsiafptauyG2vfDZhSdvMR4dz7jgvMX7Paop.json",
  "pair": {
    "symbol": "SOL",
    "mint": "So11111111111111111111111111111111111111112"
  },
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "banner": "https://zync-pad.b-cdn.net/coins/banner/0c1d2e3f4a5b6c7d8e9f0a1b.webp",
  "costSol": 0.015,
  "firstBuy": {
    "amount": "0.5",
    "coins": "in the fair opening"
  },
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### PairRef

A pair, briefly.

```ts
type PairRef = {
  symbol: string; // Ticker
  mint: string; // Token address
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `symbol` | string | Ticker |  |
| `mint` | string | Token address |  |

**Example**

```json
{
  "symbol": "SOL",
  "mint": "So11111111111111111111111111111111111111112"
}
```

### FirstBuy

Inside `LaunchResult`.

```ts
type FirstBuy = {
  amount: string; // Pair token in
  coins: string; // Coins out ("in the fair opening": they settle with everyone's at one price)
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `amount` | string | Pair token in |  |
| `coins` | string | Coins out ("in the fair opening": they settle with everyone's at one price) |  |

### TradeResult

A trade ready to sign, and what it should do.

```ts
type TradeResult = {
  transaction: string; // Base64: the trader signs it
  lastValidBlockHeight: number; // It expires after this
  side: 'buy' | 'sell'; // Buy or sell
  mode: 'instant' | 'block'; // How it fills
  amountIn: string; // What goes in
  expectedOut: string; // What should come out
  minOut: string; // The least it accepts (instant)
  priceImpactPct: number; // How far it moves the price
  fee: string; // The fee, in the pair token
  exitQueue: QueueFill | null; // Instant buys: the part filled from the Exit Queue
  block: BlockInfo | null; // Fair Block orders: the block
  swap: SwapInfo | null; // Paying with SOL on another pair: the swap leg
  next: string; // What to do with it
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `transaction` | string | Base64: the trader signs it |  |
| `lastValidBlockHeight` | integer | It expires after this |  |
| `side` | buy\|sell | Buy or sell |  |
| `mode` | instant\|block | How it fills |  |
| `amountIn` | string | What goes in |  |
| `expectedOut` | string | What should come out |  |
| `minOut` | string | The least it accepts (instant) |  |
| `priceImpactPct` | number | How far it moves the price |  |
| `fee` | string | The fee, in the pair token |  |
| `exitQueue` | [QueueFill](https://usewoop.xyz/docs/api/schemas#queuefill) or null | Instant buys: the part filled from the Exit Queue |  |
| `block` | [BlockInfo](https://usewoop.xyz/docs/api/schemas#blockinfo) or null | Fair Block orders: the block |  |
| `swap` | [SwapInfo](https://usewoop.xyz/docs/api/schemas#swapinfo) or null | Paying with SOL on another pair: the swap leg |  |
| `next` | string | What to do with it |  |

**Example**

```json
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "lastValidBlockHeight": 312345678,
  "side": "buy",
  "mode": "instant",
  "amountIn": "0.25",
  "expectedOut": "4580211.33",
  "minOut": "4442804.99",
  "priceImpactPct": 0.84,
  "fee": "0.00375",
  "exitQueue": {
    "coins": "1200000",
    "quote": "0.065",
    "dip": false,
    "discountPct": 0
  },
  "block": null,
  "swap": null,
  "next": "Sign `transaction` with `wallet`, then POST it to /api/v1/transactions."
}
```

### QueueFill

Inside `TradeResult`.

```ts
type QueueFill = {
  coins: string; // Coins from the queue
  quote: string; // Pair token spent on them
  dip: boolean; // A holder deal applied
  discountPct: number; // Its discount
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `coins` | string | Coins from the queue |  |
| `quote` | string | Pair token spent on them |  |
| `dip` | boolean | A holder deal applied |  |
| `discountPct` | number | Its discount |  |

### BlockInfo

Inside `TradeResult`.

```ts
type BlockInfo = {
  window: number; // Seconds the block collects orders before it settles
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `window` | number | Seconds the block collects orders before it settles |  |

### SwapInfo

Inside `TradeResult`.

```ts
type SwapInfo = {
  pair: string; // The pair-token leg
  leftover: string; // What stays in the wallet in the pair token
  impactPct: number; // The swap's own price impact
  via: string; // The route
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `pair` | string | The pair-token leg |  |
| `leftover` | string | What stays in the wallet in the pair token |  |
| `impactPct` | number | The swap's own price impact |  |
| `via` | string | The route |  |

### SendResult

A transaction that landed.

```ts
type SendResult = {
  kind: 'launch' | 'trade'; // launch for launches; trade for everything else
  signature: string; // The transaction signature
  mint?: string; // Launches: the new coin
  url?: string; // Launches: its page on woop
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `kind` | launch\|trade | launch for launches; trade for everything else |  |
| `signature` | string | The transaction signature |  |
| `mint` | string | Launches: the new coin | optional |
| `url` | string | Launches: its page on woop | optional |

**Example**

```json
{
  "kind": "launch",
  "signature": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
}
```

### Upload

A stored image.

```ts
type Upload = {
  url: string; // Use it as a launch's image or banner
  kind: 'image' | 'banner'; // Square coin image (512 × 512) or 3:1 banner (1500 × 500)
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `url` | string | Use it as a launch's `image` or `banner` |  |
| `kind` | image\|banner | Square coin image (512 × 512) or 3:1 banner (1500 × 500) |  |

**Example**

```json
{
  "url": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "kind": "image"
}
```

## Coins

### CoinSummary

A coin in a list.

```ts
type CoinSummary = {
  mint: string; // Its address
  name: string; // Name
  symbol: string; // Ticker
  image: string | null; // Image URL
  quoteMint: string; // Its pair's mint
  mcUsd: number | null; // Market cap, USD
  priceQuote: number | null; // Price in the pair token
  holders: number; // Wallets holding it
  graduated: boolean; // In its WAMM pool
  lastTradeAt: string | null; // ISO time of its last trade
  createdAt: string; // ISO launch time
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `mint` | string | Its address |  |
| `name` | string | Name |  |
| `symbol` | string | Ticker |  |
| `image` | string or null | Image URL |  |
| `quoteMint` | string | Its pair's mint |  |
| `mcUsd` | number or null | Market cap, USD |  |
| `priceQuote` | number or null | Price in the pair token |  |
| `holders` | integer | Wallets holding it |  |
| `graduated` | boolean | In its WAMM pool |  |
| `lastTradeAt` | string or null | ISO time of its last trade |  |
| `createdAt` | string | ISO launch time |  |

**Example**

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "name": "Moon Cat",
  "symbol": "MCAT",
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "quoteMint": "So11111111111111111111111111111111111111112",
  "mcUsd": 9640.5,
  "priceQuote": 6.34e-8,
  "holders": 128,
  "graduated": true,
  "lastTradeAt": "2026-11-01T15:20:11.000Z",
  "createdAt": "2026-11-01T14:58:36.000Z"
}
```

### Coin

One coin: everything in `CoinSummary`, plus:

```ts
type Coin = CoinSummary & {
  curve?: boolean; // On the woopcurve (then its WAMM pool)
  banner?: string | null; // 3:1 banner URL
  creator: string; // Its creator's wallet
  network: string; // mainnet or devnet
  quoteUsd: number | null; // The pair's USD price
  priceUsd: number | null; // Price, USD
  liquidityUsd: number | null; // Liquidity, USD
  paidToHoldersUsd: number | null; // Paid to holders so far, USD
  paidToHoldersQuote: number; // Paid to holders so far, pair token
  curvePct: number | null; // How far along the curve, 0–100
  top10Pct: number | null; // Share the 10 biggest wallets hold
  devPct: number | null; // Share the creator's wallet holds
  volume24hUsd: number | null; // 24h volume, USD
  change24hPct: number | null; // 24h move, %
  trades: number; // Trades so far
  fairSale?: string | null; // The fair launch that opened it, if any
};
```

| Field | Type | Description |  |
|---|---|---|---|
| … | [CoinSummary](https://usewoop.xyz/docs/api/schemas#coinsummary) | Every CoinSummary field |  |
| `curve` | boolean | On the woopcurve (then its WAMM pool) | optional |
| `banner` | string or null | 3:1 banner URL | optional |
| `creator` | string | Its creator's wallet |  |
| `network` | string | mainnet or devnet |  |
| `quoteUsd` | number or null | The pair's USD price |  |
| `priceUsd` | number or null | Price, USD |  |
| `liquidityUsd` | number or null | Liquidity, USD |  |
| `paidToHoldersUsd` | number or null | Paid to holders so far, USD |  |
| `paidToHoldersQuote` | number | Paid to holders so far, pair token |  |
| `curvePct` | number or null | How far along the curve, 0–100 |  |
| `top10Pct` | number or null | Share the 10 biggest wallets hold |  |
| `devPct` | number or null | Share the creator's wallet holds |  |
| `volume24hUsd` | number or null | 24h volume, USD |  |
| `change24hPct` | number or null | 24h move, % |  |
| `trades` | integer | Trades so far |  |
| `fairSale` | string or null | The fair launch that opened it, if any | optional |

**Example**

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "name": "Moon Cat",
  "symbol": "MCAT",
  "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
  "quoteMint": "So11111111111111111111111111111111111111112",
  "mcUsd": 9640.5,
  "priceQuote": 6.34e-8,
  "holders": 128,
  "graduated": true,
  "lastTradeAt": "2026-11-01T15:20:11.000Z",
  "createdAt": "2026-11-01T14:58:36.000Z",
  "curve": true,
  "banner": null,
  "creator": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "network": "mainnet",
  "quoteUsd": 152.1,
  "priceUsd": 0.0000096,
  "liquidityUsd": 3820.4,
  "paidToHoldersUsd": 41.27,
  "paidToHoldersQuote": 0.2713,
  "curvePct": 7.7,
  "top10Pct": 18.4,
  "devPct": 1.9,
  "volume24hUsd": 15230,
  "change24hPct": 34.2,
  "trades": 412,
  "fairSale": null
}
```

### Trade

A trade on the tape.

```ts
type Trade = {
  id: string; // Unique id
  signature: string; // Its transaction
  side: 'buy' | 'sell'; // Buy or sell
  trader: string; // The wallet
  quote: number; // Pair token in or out
  amount: number; // Coins
  usd: number | null; // In USD
  mcUsd: number | null; // Market cap at the trade, USD
  time: string; // ISO time
  via?: 'queue' | 'deal' | 'block' | 'fair'; // Filled from the Exit Queue, a holder deal, a Fair Block order or the fair launch
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `id` | string | Unique id |  |
| `signature` | string | Its transaction |  |
| `side` | buy\|sell | Buy or sell |  |
| `trader` | string | The wallet |  |
| `quote` | number | Pair token in or out |  |
| `amount` | number | Coins |  |
| `usd` | number or null | In USD |  |
| `mcUsd` | number or null | Market cap at the trade, USD |  |
| `time` | string | ISO time |  |
| `via` | queue\|deal\|block\|fair | Filled from the Exit Queue, a holder deal, a Fair Block order or the fair launch | optional |

**Example**

```json
{
  "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
  "signature": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx",
  "side": "buy",
  "trader": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "quote": 0.25,
  "amount": 4580211.33,
  "usd": 38.02,
  "mcUsd": 9640.5,
  "time": "2026-11-01T14:58:36.000Z",
  "via": "block"
}
```

### Holder

A holder and how they did.

```ts
type Holder = {
  address: string; // Wallet
  pct: number; // Share of supply
  since: string; // ISO time its holding began
  amount: number; // Coins held
  earnedQuote: number; // Paid to it for holding, pair token
  earnedUsd: number | null; // The same in USD
  boughtAmount: number; // Coins bought
  soldAmount: number; // Coins sold
  boughtQuote: number; // Pair token spent
  soldQuote: number; // Pair token received
  valueQuote: number; // Holding at the price now
  pnlQuote: number; // Profit or loss: value + sold − bought
  boughtUsd: number | null; // USD
  soldUsd: number | null; // USD
  valueUsd: number | null; // USD
  pnlUsd: number | null; // USD
  tag?: 'dev'; // The creator
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `address` | string | Wallet |  |
| `pct` | number | Share of supply |  |
| `since` | string | ISO time its holding began |  |
| `amount` | number | Coins held |  |
| `earnedQuote` | number | Paid to it for holding, pair token |  |
| `earnedUsd` | number or null | The same in USD |  |
| `boughtAmount` | number | Coins bought |  |
| `soldAmount` | number | Coins sold |  |
| `boughtQuote` | number | Pair token spent |  |
| `soldQuote` | number | Pair token received |  |
| `valueQuote` | number | Holding at the price now |  |
| `pnlQuote` | number | Profit or loss: value + sold − bought |  |
| `boughtUsd` | number or null | USD |  |
| `soldUsd` | number or null | USD |  |
| `valueUsd` | number or null | USD |  |
| `pnlUsd` | number or null | USD |  |
| `tag` | dev | The creator | optional |

**Example**

```json
{
  "address": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "pct": 0.46,
  "since": "2026-11-01T14:58:36.000Z",
  "amount": 4580211.33,
  "earnedQuote": 0.0031,
  "earnedUsd": 0.47,
  "boughtAmount": 6000000,
  "soldAmount": 1420000,
  "boughtQuote": 0.2,
  "soldQuote": 0.1,
  "valueQuote": 0.2903,
  "pnlQuote": 0.1903,
  "boughtUsd": 30.42,
  "soldUsd": 15.21,
  "valueUsd": 44.15,
  "pnlUsd": 28.94
}
```

### Candle

A market-cap candle, USD.

```ts
type Candle = {
  time: number; // Unix seconds, the candle's start
  open: number; // Open
  high: number; // High
  low: number; // Low
  close: number; // Close
  volume: number; // Volume, USD
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `time` | integer | Unix seconds, the candle's start |  |
| `open` | number | Open |  |
| `high` | number | High |  |
| `low` | number | Low |  |
| `close` | number | Close |  |
| `volume` | number | Volume, USD |  |

**Example**

```json
{
  "time": 3,
  "open": 9600,
  "high": 9800,
  "low": 9500,
  "close": 9640,
  "volume": 512.3
}
```

### Position

One wallet in one coin.

```ts
type Position = {
  wallet: string; // Wallet
  amount: number; // Coins held
  pct: number; // Share of supply
  quoteSymbolMint: string; // The pair's mint
  valueQuote: number; // Holding at the price now
  valueUsd: number | null; // USD
  paidQuote: number; // Spent on buys
  receivedQuote: number; // Got from sells
  pnlQuote: number; // Profit or loss: value + received − paid
  pnlUsd: number | null; // USD
  trades: number; // Its trades
  boughtAmount: number; // Coins bought
  soldAmount: number; // Coins sold
  since: string | null; // When its holding began
  quoteUsd: number | null; // The pair's USD price
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | Wallet |  |
| `amount` | number | Coins held |  |
| `pct` | number | Share of supply |  |
| `quoteSymbolMint` | string | The pair's mint |  |
| `valueQuote` | number | Holding at the price now |  |
| `valueUsd` | number or null | USD |  |
| `paidQuote` | number | Spent on buys |  |
| `receivedQuote` | number | Got from sells |  |
| `pnlQuote` | number | Profit or loss: value + received − paid |  |
| `pnlUsd` | number or null | USD |  |
| `trades` | integer | Its trades |  |
| `boughtAmount` | number | Coins bought |  |
| `soldAmount` | number | Coins sold |  |
| `since` | string or null | When its holding began |  |
| `quoteUsd` | number or null | The pair's USD price |  |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "amount": 4580211.33,
  "pct": 0.46,
  "quoteSymbolMint": "So11111111111111111111111111111111111111112",
  "valueQuote": 0.2903,
  "valueUsd": 44.15,
  "paidQuote": 0.2,
  "receivedQuote": 0.1,
  "pnlQuote": 0.1903,
  "pnlUsd": 28.94,
  "trades": 412,
  "boughtAmount": 6000000,
  "soldAmount": 1420000,
  "since": "2026-11-01T14:58:36.000Z",
  "quoteUsd": 152.1
}
```

### Payout

An hourly payout to holders.

```ts
type Payout = {
  epoch: number; // Its number
  rewardMint: string; // What it paid in (the pair token)
  amount: number; // Paid in total
  amountUsd: number | null; // USD
  holders: number; // Holders paid
  postedAt: string; // ISO
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `epoch` | integer | Its number |  |
| `rewardMint` | string | What it paid in (the pair token) |  |
| `amount` | number | Paid in total |  |
| `amountUsd` | number or null | USD |  |
| `holders` | integer | Holders paid |  |
| `postedAt` | string | ISO |  |

**Example**

```json
{
  "epoch": 37,
  "rewardMint": "So11111111111111111111111111111111111111112",
  "amount": 0.0271,
  "amountUsd": 4.12,
  "holders": 128,
  "postedAt": "2026-11-01T15:00:00.000Z"
}
```

### Event

Something that happened on the coin besides a plain trade.

```ts
type Event = {
  time: number; // Unix seconds
  kind: 'payout' | 'promoter' | 'fairblock' | 'exit' | 'creator'; // Holder payout, promoter fee, Fair Block settled, Exit Queue fill or creator fees
  usd: number | null; // How much, USD
  n?: number; // Fair Blocks: orders in it
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `time` | integer | Unix seconds |  |
| `kind` | payout\|promoter\|fairblock\|exit\|creator | Holder payout, promoter fee, Fair Block settled, Exit Queue fill or creator fees |  |
| `usd` | number or null | How much, USD |  |
| `n` | integer | Fair Blocks: orders in it | optional |

**Example**

```json
{
  "time": 3,
  "kind": "fairblock",
  "usd": 94.9,
  "n": 14
}
```

### Signals

Rug signals from on-chain history.

```ts
type Signals = {
  devFunder: string | null; // The wallet that first funded the creator
  devFundedByExchange: boolean; // Funded from an exchange
  linked: WalletGroup; // Holders funded by the creator, or who funded them
  snipers: WalletGroup; // Wallets that bought in the first 10 seconds
  bundled: WalletGroup; // Wallets that bought in the same block as the first trade
  lock: SignalLock | null; // A creator lock set at launch (older coins)
  checked: number; // Holders checked
  holders: number; // Holders
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `devFunder` | string or null | The wallet that first funded the creator |  |
| `devFundedByExchange` | boolean | Funded from an exchange |  |
| `linked` | [WalletGroup](https://usewoop.xyz/docs/api/schemas#walletgroup) | Holders funded by the creator, or who funded them |  |
| `snipers` | [WalletGroup](https://usewoop.xyz/docs/api/schemas#walletgroup) | Wallets that bought in the first 10 seconds |  |
| `bundled` | [WalletGroup](https://usewoop.xyz/docs/api/schemas#walletgroup) | Wallets that bought in the same block as the first trade |  |
| `lock` | [SignalLock](https://usewoop.xyz/docs/api/schemas#signallock) or null | A creator lock set at launch (older coins) |  |
| `checked` | integer | Holders checked |  |
| `holders` | integer | Holders |  |

**Example**

```json
{
  "devFunder": "3Qx9vLm2TnB8rJ5cWzXy7kP4sF1gH6dA9eN0bRtUoVi",
  "devFundedByExchange": true,
  "linked": {
    "wallets": [],
    "pct": 0
  },
  "snipers": {
    "wallets": [],
    "pct": 0
  },
  "bundled": {
    "wallets": [],
    "pct": 0
  },
  "lock": null,
  "checked": 40,
  "holders": 128
}
```

### WalletGroup

Inside `Signals`.

```ts
type WalletGroup = {
  wallets: string[]; // The wallets
  pct: number; // Share of supply they hold
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallets` | string[] | The wallets |  |
| `pct` | number | Share of supply they hold |  |

### SignalLock

Inside `Signals`.

```ts
type SignalLock = {
  pct: number; // Share of supply
  cliffDays: number; // Days before it unlocks
  unlockDays: number; // Days it unlocks over
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `pct` | number | Share of supply |  |
| `cliffDays` | number | Days before it unlocks |  |
| `unlockDays` | number | Days it unlocks over |  |

## The woopcurve

### Curve

A woopcurve coin's state.

```ts
type Curve = {
  status: 'opening' | 'trading' | 'block-pending' | 'complete' | 'graduated' | 'refund'; // Where it is
  quoteDecimals: number; // The pair's decimals
  raised: number; // Pair token in the curve
  target: number; // What graduation takes
  soldPct: number; // Share of the curve's 760M coins sold
  mcap: Mcaps; // Market caps, pair token
  graduatedAt: string | null; // When it moved into its WAMM pool
  pool: Pool | null; // Its WAMM pool
  openingEndsAt: string | null; // When the fair opening ends
  blockClosesAt: string | null; // When the open Fair Block settles
  refundAt: string | null; // When refunds start if it hasn't graduated
  advance: Advance; // The creator's 1 SOL launch advance
  creator: CreatorLock; // The creator's locked coins
  creatorFeesOwed: number; // Creator fees waiting for the next payout
  fees: Fees; // Its fees
  mine?: CurveMine; // With ?wallet=: that wallet's side
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `status` | opening\|trading\|block-pending\|complete\|graduated\|refund | Where it is |  |
| `quoteDecimals` | integer | The pair's decimals |  |
| `raised` | number | Pair token in the curve |  |
| `target` | number | What graduation takes |  |
| `soldPct` | number | Share of the curve's 760M coins sold |  |
| `mcap` | [Mcaps](https://usewoop.xyz/docs/api/schemas#mcaps) | Market caps, pair token |  |
| `graduatedAt` | string or null | When it moved into its WAMM pool |  |
| `pool` | [Pool](https://usewoop.xyz/docs/api/schemas#pool) or null | Its WAMM pool |  |
| `openingEndsAt` | string or null | When the fair opening ends |  |
| `blockClosesAt` | string or null | When the open Fair Block settles |  |
| `refundAt` | string or null | When refunds start if it hasn't graduated |  |
| `advance` | [Advance](https://usewoop.xyz/docs/api/schemas#advance) | The creator's 1 SOL launch advance |  |
| `creator` | [CreatorLock](https://usewoop.xyz/docs/api/schemas#creatorlock) | The creator's locked coins |  |
| `creatorFeesOwed` | number | Creator fees waiting for the next payout |  |
| `fees` | [Fees](https://usewoop.xyz/docs/api/schemas#fees) | Its fees |  |
| `mine` | [CurveMine](https://usewoop.xyz/docs/api/schemas#curvemine) | With ?wallet=: that wallet's side | optional |

**Example**

```json
{
  "status": "trading",
  "quoteDecimals": 9,
  "raised": 9.68,
  "target": 125.8,
  "soldPct": 7.1,
  "mcap": {
    "start": 33,
    "now": 63.4,
    "graduation": 328.8
  },
  "graduatedAt": null,
  "pool": null,
  "openingEndsAt": null,
  "blockClosesAt": null,
  "refundAt": "2026-11-01T14:58:36.000Z",
  "advance": {
    "amount": 4580211.33,
    "repaid": 0.06,
    "owed": 0.94
  },
  "creator": {
    "locked": 18791167.7,
    "vest": 0,
    "claimed": 0,
    "claimable": 0,
    "unlockDays": 10,
    "cliffDays": 0,
    "graduatedAt": null
  },
  "creatorFeesOwed": 0.0042,
  "fees": {
    "trade": 1.5,
    "instant": 10,
    "exit": 1,
    "pool": 1.5,
    "tierHalf": true,
    "split": {
      "trade": [
        0.6,
        0.5,
        0.4
      ],
      "instant": [
        0.5,
        0.25,
        0.25
      ],
      "exit": [
        0.5,
        0.25,
        0.25
      ],
      "pool": [
        0.6,
        0.5,
        0.4
      ]
    }
  },
  "mine": {
    "order": null,
    "exits": [
      {
        "slot": 0,
        "left": 4000000,
        "owed": 0.94,
        "floorPct": -5
      }
    ],
    "instantMax": 916042.2,
    "instantNextAt": null,
    "refund": null
  }
}
```

### Mcaps

Inside `Curve`.

```ts
type Mcaps = {
  start: number; // At launch
  now: number; // Now
  graduation: number; // Where it graduates
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `start` | number | At launch |  |
| `now` | number | Now |  |
| `graduation` | number | Where it graduates |  |

### Pool

Inside `Curve`.

```ts
type Pool = {
  quote: number; // Pair token
  coins: number; // Coins
  burned: number; // Coins burned at graduation
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `quote` | number | Pair token |  |
| `coins` | number | Coins |  |
| `burned` | number | Coins burned at graduation |  |

### Advance

Inside `Curve`.

```ts
type Advance = {
  amount: number; // The advance
  repaid: number; // Repaid from creator fees
  owed: number; // Still owed
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `amount` | number | The advance |  |
| `repaid` | number | Repaid from creator fees |  |
| `owed` | number | Still owed |  |

### CreatorLock

Inside `Curve`.

```ts
type CreatorLock = {
  locked: number; // Coins locked
  vest: number; // Coins unlocking
  claimed: number; // Coins taken
  claimable: number; // Coins the creator can take now
  unlockDays: number; // Days they unlock over
  cliffDays: number; // Days before unlocking starts
  graduatedAt: string | null; // When the unlock clock started
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `locked` | number | Coins locked |  |
| `vest` | number | Coins unlocking |  |
| `claimed` | number | Coins taken |  |
| `claimable` | number | Coins the creator can take now |  |
| `unlockDays` | integer | Days they unlock over |  |
| `cliffDays` | integer | Days before unlocking starts |  |
| `graduatedAt` | string or null | When the unlock clock started |  |

### Fees

Inside `Curve`. Percent of the trade.

```ts
type Fees = {
  trade: number; // Curve trades and Fair Blocks
  instant: number; // Instant sells
  exit: number; // Exit Queue, each side
  pool: number; // WAMM pool trades
  tierHalf: boolean; // Holders of 100k $WOOP pay half
  split: FeeSplit; // Each fee split between holders, the creator and woop
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `trade` | number | Curve trades and Fair Blocks |  |
| `instant` | number | Instant sells |  |
| `exit` | number | Exit Queue, each side |  |
| `pool` | number | WAMM pool trades |  |
| `tierHalf` | boolean | Holders of 100k $WOOP pay half |  |
| `split` | [FeeSplit](https://usewoop.xyz/docs/api/schemas#feesplit) | Each fee split between holders, the creator and woop |  |

### FeeSplit

Inside `Fees`: [holders, creator, woop], percent of the trade.

```ts
type FeeSplit = {
  trade: number[];
  instant: number[];
  exit: number[];
  pool: number[];
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `trade` | number[] |  |  |
| `instant` | number[] |  |  |
| `exit` | number[] |  |  |
| `pool` | number[] |  |  |

### CurveMine

Inside `Curve`.

```ts
type CurveMine = {
  order: MyOrder | null; // Its Fair Block order
  exits: MyExit[]; // Its Exit Queue orders
  instantMax: number; // The most it can instant-sell now
  instantNextAt: string | null; // When its next instant sell is allowed
  refund: MyRefund | null; // Its refund, in refund mode
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `order` | [MyOrder](https://usewoop.xyz/docs/api/schemas#myorder) or null | Its Fair Block order |  |
| `exits` | [MyExit](https://usewoop.xyz/docs/api/schemas#myexit)[] | Its Exit Queue orders |  |
| `instantMax` | number | The most it can instant-sell now |  |
| `instantNextAt` | string or null | When its next instant sell is allowed |  |
| `refund` | [MyRefund](https://usewoop.xyz/docs/api/schemas#myrefund) or null | Its refund, in refund mode |  |

### MyOrder

Inside `CurveMine`.

```ts
type MyOrder = {
  buy: boolean; // A buy
  amount: number; // Its amount
  settled: boolean; // Its block settled
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `buy` | boolean | A buy |  |
| `amount` | number | Its amount |  |
| `settled` | boolean | Its block settled |  |

### MyExit

Inside `CurveMine`.

```ts
type MyExit = {
  slot: number; // For cancelling
  left: number; // Coins left
  owed: number; // Proceeds waiting
  floorPct: number; // Its floor against now
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `slot` | integer | For cancelling |  |
| `left` | number | Coins left |  |
| `owed` | number | Proceeds waiting |  |
| `floorPct` | number | Its floor against now |  |

### MyRefund

Inside `CurveMine`.

```ts
type MyRefund = {
  estimate: number; // About what it gets back
  paid: boolean; // Already paid
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `estimate` | number | About what it gets back |  |
| `paid` | boolean | Already paid |  |

## Exit Queue

### Queue

A coin's Exit Queue.

```ts
type Queue = {
  spot: number; // Price now, pair token per coin
  quoteDecimals: number; // The pair's decimals
  orders: QueueOrder[]; // Orders waiting now
  totalQueued: number; // Coins waiting
  graduated: boolean; // Fills at the pool's price
  feePct: number; // Fee per side
  tierFeePct: number; // Fee per side for $WOOP holders
  tier: boolean; // With ?wallet=: it pays the lower fee
  history: QueueHistory[]; // Every order the queue has had, newest first
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `spot` | number | Price now, pair token per coin |  |
| `quoteDecimals` | integer | The pair's decimals |  |
| `orders` | [QueueOrder](https://usewoop.xyz/docs/api/schemas#queueorder)[] | Orders waiting now |  |
| `totalQueued` | number | Coins waiting |  |
| `graduated` | boolean | Fills at the pool's price |  |
| `feePct` | number | Fee per side |  |
| `tierFeePct` | number | Fee per side for $WOOP holders |  |
| `tier` | boolean | With ?wallet=: it pays the lower fee |  |
| `history` | [QueueHistory](https://usewoop.xyz/docs/api/schemas#queuehistory)[] | Every order the queue has had, newest first |  |

**Example**

```json
{
  "spot": 6.34e-8,
  "quoteDecimals": 9,
  "orders": [
    {
      "slot": 0,
      "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
      "seller": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
      "remaining": 12000000,
      "floor": 6.02e-8,
      "floorPct": -5,
      "proceeds": 0.31,
      "mine": true
    }
  ],
  "totalQueued": 12000000,
  "graduated": true,
  "feePct": 1,
  "tierFeePct": 0.5,
  "tier": true,
  "history": [
    {
      "id": "5hqJ7pHZnPTXqbQZfSTSwTPL46q6hSf2ahJ1A5KHNg3DC2NCtcEgDqWZePRYTkcP5Du6GeWqz3NKNL1MdvHJcBfx:1000",
      "seller": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
      "mine": true,
      "amount": 8000000,
      "filled": 8000000,
      "received": 0.49,
      "floor": 6.02e-8,
      "status": "filled",
      "placedAt": "2026-11-01T15:02:10.000Z",
      "closedAt": null,
      "slot": null
    }
  ]
}
```

### QueueOrder

Inside `Queue`.

```ts
type QueueOrder = {
  slot: number; // For cancelling
  id: string; // Id
  seller: string; // Wallet
  remaining: number; // Coins left
  floor: number; // Lowest price, pair token per coin
  floorPct: number; // Floor against now, %
  proceeds: number; // Sold for so far, waiting to be paid
  mine: boolean; // With ?wallet=: its own
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `slot` | integer | For cancelling |  |
| `id` | string | Id |  |
| `seller` | string | Wallet |  |
| `remaining` | number | Coins left |  |
| `floor` | number | Lowest price, pair token per coin |  |
| `floorPct` | number | Floor against now, % |  |
| `proceeds` | number | Sold for so far, waiting to be paid |  |
| `mine` | boolean | With ?wallet=: its own |  |

### QueueHistory

Inside `Queue`.

```ts
type QueueHistory = {
  id: string; // Id
  seller: string; // Wallet
  mine: boolean; // With ?wallet=: its own
  amount: number; // Coins queued
  filled: number; // Coins sold
  received: number; // Pair token the seller got
  floor: number; // Lowest price, pair token per coin
  status: 'waiting' | 'filled' | 'partly' | 'cancelled'; // Where it ended (or is)
  placedAt: string | null; // ISO
  closedAt: string | null; // ISO, when cancelled
  slot: number | null; // Waiting orders: for cancelling
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `id` | string | Id |  |
| `seller` | string | Wallet |  |
| `mine` | boolean | With ?wallet=: its own |  |
| `amount` | number | Coins queued |  |
| `filled` | number | Coins sold |  |
| `received` | number | Pair token the seller got |  |
| `floor` | number | Lowest price, pair token per coin |  |
| `status` | waiting\|filled\|partly\|cancelled | Where it ended (or is) |  |
| `placedAt` | string or null | ISO |  |
| `closedAt` | string or null | ISO, when cancelled |  |
| `slot` | integer or null | Waiting orders: for cancelling |  |

## Pairs, tickers, wallets, you

### Pair

A token a coin can launch against. Holders are paid in it.

```ts
type Pair = {
  symbol: string; // Its ticker, e.g. SOL
  name: string; // Its name
  mint: string; // Its token address
  category: string; // Crypto, Dollars, Commodities, Memes…
  logo: string | null; // Logo URL
  decimals: number; // Its decimals
  graduationRaise: number; // How much of it a coin on this pair raises to graduate
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `symbol` | string | Its ticker, e.g. SOL |  |
| `name` | string | Its name |  |
| `mint` | string | Its token address |  |
| `category` | string | Crypto, Dollars, Commodities, Memes… |  |
| `logo` | string or null | Logo URL |  |
| `decimals` | integer | Its decimals |  |
| `graduationRaise` | number | How much of it a coin on this pair raises to graduate |  |

**Example**

```json
{
  "symbol": "SOL",
  "name": "Solana",
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "category": "Crypto",
  "logo": "https://zync-pad.b-cdn.net/pairs/So11111111111111111111111111111111111111112.webp",
  "decimals": 9,
  "graduationRaise": 125.8
}
```

### Ticker

Whether a ticker is free.

```ts
type Ticker = {
  symbol: string; // The ticker, upper case
  available: boolean; // Free to use at no extra cost
  takenBy?: TickerOwner; // The coin that has it
  copyFeeSol?: number; // What using it anyway costs, paid to that coin's holders
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `symbol` | string | The ticker, upper case |  |
| `available` | boolean | Free to use at no extra cost |  |
| `takenBy` | [TickerOwner](https://usewoop.xyz/docs/api/schemas#tickerowner) | The coin that has it | optional |
| `copyFeeSol` | number | What using it anyway costs, paid to that coin's holders | optional |

**Example**

```json
{
  "symbol": "MCAT",
  "available": false,
  "takenBy": {
    "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
    "name": "Moon Cat"
  },
  "copyFeeSol": 1
}
```

### TickerOwner

Inside `Ticker`.

```ts
type TickerOwner = {
  mint: string; // The coin with the ticker
  name: string; // Its name
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `mint` | string | The coin with the ticker |  |
| `name` | string | Its name |  |

### Portfolio

A wallet's woop coins.

```ts
type Portfolio = {
  holdings: Holding[]; // Coins it holds or earned from, biggest first
  totals: PortfolioTotals; // Totals
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `holdings` | [Holding](https://usewoop.xyz/docs/api/schemas#holding)[] | Coins it holds or earned from, biggest first |  |
| `totals` | [PortfolioTotals](https://usewoop.xyz/docs/api/schemas#portfoliototals) | Totals |  |

**Example**

```json
{
  "holdings": [
    {
      "coin": {
        "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
        "name": "Moon Cat",
        "symbol": "MCAT",
        "image": "https://zync-pad.b-cdn.net/coins/img/a9788d7c9762b17650551eb2.webp",
        "quoteMint": "So11111111111111111111111111111111111111112",
        "mcUsd": 9640.5,
        "priceQuote": 6.34e-8,
        "holders": 128,
        "graduated": true,
        "lastTradeAt": "2026-11-01T15:20:11.000Z",
        "createdAt": "2026-11-01T14:58:36.000Z",
        "curve": true,
        "banner": null,
        "creator": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
        "network": "mainnet",
        "quoteUsd": 152.1,
        "priceUsd": 0.0000096,
        "liquidityUsd": 3820.4,
        "paidToHoldersUsd": 41.27,
        "paidToHoldersQuote": 0.2713,
        "curvePct": 7.7,
        "top10Pct": 18.4,
        "devPct": 1.9,
        "volume24hUsd": 15230,
        "change24hPct": 34.2,
        "trades": 412,
        "fairSale": null
      },
      "amount": 4580211.33,
      "pct": 0.46,
      "valueUsd": 44.15,
      "since": "2026-11-01T14:58:36.000Z",
      "earnedQuote": 0.0031,
      "earnedUsd": 0.47,
      "claimable": [],
      "claimableUsd": 0
    }
  ],
  "totals": {
    "valueUsd": 44.15,
    "earnedUsd": 0.47,
    "claimableUsd": 0,
    "claimableCount": 0,
    "coins": 3
  }
}
```

### Holding

Inside `Portfolio`.

```ts
type Holding = {
  coin: Coin; // The coin
  amount: number; // Coins held
  pct: number; // Share of supply
  valueUsd: number | null; // USD
  since: string | null; // Holding since
  earnedQuote: number; // Paid for holding, pair token
  earnedUsd: number | null; // USD
  claimable: Claimable[]; // Rewards it can still claim (most are paid automatically)
  claimableUsd: number | null; // USD
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `coin` | [Coin](https://usewoop.xyz/docs/api/schemas#coin) | The coin |  |
| `amount` | number | Coins held |  |
| `pct` | number | Share of supply |  |
| `valueUsd` | number or null | USD |  |
| `since` | string or null | Holding since |  |
| `earnedQuote` | number | Paid for holding, pair token |  |
| `earnedUsd` | number or null | USD |  |
| `claimable` | [Claimable](https://usewoop.xyz/docs/api/schemas#claimable)[] | Rewards it can still claim (most are paid automatically) |  |
| `claimableUsd` | number or null | USD |  |

### Claimable

Inside `Holding`.

```ts
type Claimable = {
  rewardMint: string; // Paid in
  amount: number; // Amount
  amountUsd: number | null; // USD
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `rewardMint` | string | Paid in |  |
| `amount` | number | Amount |  |
| `amountUsd` | number or null | USD |  |

### PortfolioTotals

Inside `Portfolio`.

```ts
type PortfolioTotals = {
  valueUsd: number | null; // Holdings, USD
  earnedUsd: number | null; // Earned, USD
  claimableUsd: number | null; // Claimable, USD
  claimableCount: number; // Coins with something to claim
  coins: number; // Coins held
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `valueUsd` | number or null | Holdings, USD |  |
| `earnedUsd` | number or null | Earned, USD |  |
| `claimableUsd` | number or null | Claimable, USD |  |
| `claimableCount` | integer | Coins with something to claim |  |
| `coins` | integer | Coins held |  |

### Me

Your key and what it launched.

```ts
type Me = {
  wallet: string; // The key's wallet
  key: KeyUsage; // The key
  launches: ApiLaunch[]; // Coins launched through the API
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `wallet` | string | The key's wallet |  |
| `key` | [KeyUsage](https://usewoop.xyz/docs/api/schemas#keyusage) | The key |  |
| `launches` | [ApiLaunch](https://usewoop.xyz/docs/api/schemas#apilaunch)[] | Coins launched through the API |  |

**Example**

```json
{
  "wallet": "8hyPWptPNa47TCinJbopyjF2H92kkpt2xCvCwF1ivMh6",
  "key": {
    "prefix": "woop_AKPH67r",
    "createdAt": "2026-11-01T14:58:36.000Z",
    "lastUsedAt": "2026-11-01T14:58:36.000Z",
    "requests": 1840
  },
  "launches": [
    {
      "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
      "name": "Moon Cat",
      "symbol": "MCAT",
      "launchedAt": "2026-11-01T14:58:36.000Z",
      "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
    }
  ]
}
```

### KeyUsage

Inside `Me`.

```ts
type KeyUsage = {
  prefix: string; // Its first characters
  createdAt: string; // ISO
  lastUsedAt: string | null; // ISO
  requests: number; // Requests made with it
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `prefix` | string | Its first characters |  |
| `createdAt` | string | ISO |  |
| `lastUsedAt` | string or null | ISO |  |
| `requests` | integer | Requests made with it |  |

### ApiLaunch

A coin launched through the API.

```ts
type ApiLaunch = {
  mint: string; // Its address
  name: string | null; // Name
  symbol: string | null; // Ticker
  launchedAt: string; // ISO
  url: string; // Its page on woop
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `mint` | string | Its address |  |
| `name` | string or null | Name |  |
| `symbol` | string or null | Ticker |  |
| `launchedAt` | string | ISO |  |
| `url` | string | Its page on woop |  |

**Example**

```json
{
  "mint": "6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp",
  "name": "Moon Cat",
  "symbol": "MCAT",
  "launchedAt": "2026-11-01T14:58:36.000Z",
  "url": "https://usewoop.xyz/coin/6D162EwSMepWrTJNxAyfHM3RBBG5pgSQy9mLvrZBS9Pp"
}
```

## Errors

### Error

Every failed request.

```ts
type Error = {
  error: ErrorBody; // What went wrong
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `error` | [ErrorBody](https://usewoop.xyz/docs/api/schemas#errorbody) | What went wrong |  |

**Example**

```json
{
  "error": {
    "code": "pair_not_open",
    "message": "`DOGE` isn’t a pair you can launch on. GET /api/v1/pairs lists them."
  }
}
```

### ErrorBody

Inside `Error`.

```ts
type ErrorBody = {
  code: string; // Stable code to branch on: see Errors and limits
  message: string; // A plain sentence you can show to a user
};
```

| Field | Type | Description |  |
|---|---|---|---|
| `code` | string | Stable code to branch on: see Errors and limits |  |
| `message` | string | A plain sentence you can show to a user |  |