# Surplus LLM launchpad: guide for AI agents and CLIs

Launch a token for your own Hugging Face model on Robinhood Chain, from a script or an AI agent instead of the web wizard at https://surplusllm.com/launchpad/model. The token launches on Pons V2 or, while `flywheel.open` is `true` in `GET /api/launchpad/config`, on Flywheel's native Uniswap v4 launchpad. If it graduates, Surplus serves the model through its OpenAI-compatible API.

Ready-made script: https://surplusllm.com/agents/launch.mjs (Node 20+, needs `viem@2`).

## Rules for agents

- **The launcher's wallet must sign the launch itself.** Pons records `msg.sender` as the deployer, and Surplus only lists launches whose deployer is the wallet that prepared them. On Flywheel the splitter address is derived from the sending wallet, so a launch sent from another wallet never matches its prepared launch. Never launch for someone else from your own wallet.
- **Confirm with your human before sending the launch** (`launchToken` on Pons, `launch` on the Flywheel splitter factory). It costs the launch fee (0.0005 ETH today on both, read `launchFee()` / `launchValue()`) plus gas, and a launch can't be undone or edited.
- **Never change `creatorFeeRecipient`, `creatorTaxBps`, `buybackEnabled`, `description` or `salt`** from what `prepare` returned. A launch that differs is rejected at registration and never served.
- **No dev buy.** Surplus launches have no dev buy: the launcher ships the model and the market buys the token. If the launcher wallet buys on the token's Pons curve (as buyer or as recipient), or receives the token out of its Flywheel pool or Flywheel's router before graduation, the launch is delisted for good and its model is never served.
- Keep the private key in an environment variable or a signer you control. Never paste it into prompts, logs or files.

## Constants

| What | Value |
|---|---|
| API origin | `https://api.surplusllm.com` |
| Chain | Robinhood Chain, id `4663`, RPC `https://rpc.mainnet.chain.robinhood.com`, gas in ETH |
| SIWE domain | `surplusllm.com` (URI `https://surplusllm.com`) |
| Pons V2 launch factory | `0x7ed598bcef8bd9edd8c97a195c6d13f40801ec7e` |
| Surplus splitter factory | `0xda0a6f769aefff08c27741192ea32d21330c466b` |
| Pons launch config | `0` (1B supply, ETH pair, graduates at 4.2 ETH) |
| Flywheel launch factory | `0xf05a26e92e27b8f0385f6895f5507db26a2f4b8d` (you call Surplus's splitter factory, which calls it) |
| Surplus Flywheel splitter factory | `flywheel.splitterFactory` in `GET /api/launchpad/config` |
| Flywheel launch terms | ETH pair, 100B supply, graduates when its pool raises the factory's `target()` (about 4.17 ETH); 4% trading tax, 2.95% of volume to the creator |
| Creator fee split (Launchpad V2, every launch since 2026-10-29; `v2` in `GET /api/launchpad/config`) | 10% buys and burns the launch's own token, 30% launcher, 20% buys and burns $SURPLUS, 20% $SURPLUS stakers in USDG (weekly), 20% Inference Fund (both platforms) |
| Earlier launches | 10% buys and burns $SURPLUS, 60% hosting vault, 30% launcher |

Live values: `GET https://api.surplusllm.com/api/launchpad/config`.

## Step 1: make the model eligible

The model must be on Hugging Face, and Surplus checks the **head of the `main` branch** when you call `prepare`:

- Public repo, not gated, not disabled.
- Weights in safetensors, 20B to 32B parameters (`minModelParams` / `maxModelParams` in `GET /api/launchpad/config`). The model runs on its own 48 GB GPU, quantized to FP8 at load, at $0.10 per 1M tokens. Launches under 20B made before this rule keep serving on a 24 GB GPU at $0.03.
- Architecture (first entry of `config.json` `architectures`) is one of: `LlamaForCausalLM`, `MistralForCausalLM`, `MixtralForCausalLM`, `Qwen2ForCausalLM`, `Qwen3ForCausalLM`, `Qwen3MoeForCausalLM`, `Gemma2ForCausalLM`, `Gemma3ForCausalLM`, `Gemma4ForCausalLM`, `Gemma4ForConditionalGeneration`, `MuseGlimmerForCausalLM`, `MuseGlimmerForConditionalGeneration`, `Phi3ForCausalLM`, `GraniteForCausalLM`, `OlmoForCausalLM`, `Olmo2ForCausalLM`. MLX builds of a `…ForConditionalGeneration` model are rejected: upload standard safetensors (bf16, AWQ, GPTQ or FP8).
- A chat template: `chat_template` in `tokenizer_config.json`, or a `chat_template.jinja` / `chat_template.json` file at the repo root.
- Model card `license` is one of: `apache-2.0`, `mit`, `bsd-3-clause`, `llama3`, `llama3.1`, `llama3.2`, `llama3.3`, `gemma`.
- `README.md` on `main` contains this line, with the launcher wallet's address (case doesn't matter):

```
surplus-launcher: 0xYourLauncherWallet
```

Pre-check without signing anything:

```bash
curl -s https://huggingface.co/api/models/ORG/REPO/revision/main | jq '{sha, private, gated, params: .safetensors.total, arch: .config.architectures[0], chat: (.config.tokenizer_config.chat_template != null or .config.chat_template_jinja != null or ([.siblings[].rfilename] | any(. == "chat_template.jinja" or . == "chat_template.json"))), license: .cardData.license}'
```

Commits after `prepare` don't matter: the launch pins the sha that `prepare` returned. A new model version needs a new launch.

## Step 2: sign in (SIWE)

`prepare` needs a session cookie. All responses use `{ "success": bool, "data": …, "error": string | null }`.

1. `POST /api/auth/nonce` with body `{}` → `data.nonce`.
2. Build an EIP-4361 message: domain `surplusllm.com`, URI `https://surplusllm.com`, chain id `4663`, version `1`, that nonce, the launcher address. Sign it with `personal_sign`.
3. `POST /api/auth/verify` with `{ "message", "signature" }`. Keep the `surplus_session` cookie from `Set-Cookie` and send it as `Cookie: surplus_session=…` on `prepare`.

Signing in costs no gas. Smart-contract wallets work (ERC-1271/6492).

## Step 3: prepare

```
POST /api/launchpad/prepare
Cookie: surplus_session=…
Content-Type: application/json

{ "repo": "org/model" }
```

Optional `"platform"`: `"pons"` (the default) or `"flywheel"` while `flywheel.open` is `true`. A Flywheel launch pairs with ETH only, so don't send `pair` with it; its response is under Step 4b.

Optional `"pair"` (Pons only): a stock symbol from `stockPairs.pairs` in `GET /api/launchpad/config` (e.g. `SPY`, `NVDA`, `META`). Only while `stockPairs.open` is `true` and that stock's `health` is `"ok"`; otherwise leave it out for an ETH launch. A stock-paired launch's fees arrive in the stock and are converted to USDG (hosting, the builder's 30% and the burn). Robinhood issues the stock tokens, can pause or block them, and doesn't offer them to U.S. persons.

`200` returns, for Pons:

```json
{
  "id": "…",
  "hfRepo": "org/model",
  "hfSha": "40-hex commit",
  "modelHash": "0x…",
  "splitter": "0x…",
  "splitterSalt": "0x…",
  "ponsFactory": "0x7ed598bcef8bd9edd8c97a195c6d13f40801ec7e",
  "pairToken": "0x0000000000000000000000000000000000000000 (ETH) or the stock token",
  "pairSymbol": null,
  "tokenParams": {
    "creatorFeeRecipient": "0x… (the splitter)",
    "creatorTaxBps": 200,
    "buybackEnabled": false,
    "description": "hf:org/model@<sha>",
    "salt": "0x…"
  }
}
```

For Flywheel:

```json
{
  "platform": "flywheel",
  "id": "…",
  "hfRepo": "org/model",
  "hfSha": "40-hex commit",
  "modelHash": "0x…",
  "splitter": "0x… (reserved: deployed by your launch tx)",
  "splitterSalt": "0x…",
  "flywheelSplitterFactory": "0x…",
  "pairToken": "0x0000000000000000000000000000000000000000",
  "pairSymbol": null,
  "description": "hf:org/model@<sha>"
}
```

| Status | Meaning |
|---|---|
| 400 | `repo` is not `org/name`, an unknown `platform`, or a stock `pair` with Flywheel |
| 401 | Not signed in, or the session expired |
| 404 | Repo or its `main` branch not found |
| 422 | Model fails a check; `error` says which one and how to fix it |
| 429 | Rate limited, or 5 prepared-but-unlaunched launches in the last day for this wallet |
| 503 | Hugging Face or Robinhood Chain unreachable, or Flywheel launches not open; retry |

Every `prepare` reserves a new splitter. A prepared launch that is never registered expires after 7 days.

### Optional: upload a logo

```
POST /api/launchpad/logo
Cookie: surplus_session=…
Content-Type: application/json

{ "data": "<base64 of a PNG, JPEG, WebP or GIF, up to 512 KB>" }
```

`200` returns `{ "url": "https://api.surplusllm.com/api/launchpad/logos/<sha256>.<ext>" }`. Use it as `logo`. The URL is permanent and content-addressed. `400` means the file isn't a supported image or is too large.

## Step 4: launch on Pons

From the launcher wallet, call `launchToken(params, 0, pairToken)` on the Pons factory with `value = launchFee()`, where `pairToken` is the one `prepare` returned (`address(0)` for ETH).

```solidity
struct Socials { string twitter; string telegram; string discord; string website; string farcaster; }
struct TokenParams {
  string name; string symbol; string logo; string description; Socials socials;
  address creatorFeeRecipient; uint16 creatorTaxBps; bool buybackEnabled;
  bytes32 expectedEconomics; bytes32 salt;
}
function launchFee() view returns (uint256);
function previewLaunchEconomics(uint256 launchConfigId, address pairToken) view returns (bytes32);
function launchToken(TokenParams params, uint256 launchConfigId, address pairToken) payable returns (address token, address curve);
```

Fill `TokenParams` like this:

| Field | Value |
|---|---|
| `name` | 1-32 characters |
| `symbol` | 1-10 of `A-Z0-9` |
| `logo` | `https://…` or `ipfs://…`, the URL from `POST /api/launchpad/logo`, or empty |
| `description` | `tokenParams.description` from prepare |
| `socials` | `twitter` as `https://x.com/<handle>`, `website` as `https://…`; others empty |
| `creatorFeeRecipient` | `tokenParams.creatorFeeRecipient` from prepare |
| `creatorTaxBps` | `tokenParams.creatorTaxBps` from prepare |
| `buybackEnabled` | `false` |
| `expectedEconomics` | `previewLaunchEconomics(0, pairToken)`, read right before sending |
| `salt` | `tokenParams.salt` from prepare |

`expectedEconomics` makes the tx revert, instead of launching on new terms, if Pons changes its curve economics between your read and the tx.

## Step 4b: launch on Flywheel

From the launcher wallet, call `launch(request)` on `flywheelSplitterFactory` with `value = launchValue()`. In one transaction it deploys your splitter at the reserved address and has it launch the token on Flywheel, so the splitter is the token's permanent creator and every creator reward goes through the Launchpad V2 split.

```solidity
struct FlywheelMetadata { string logoURI; string description; string website; string twitter; string telegram; }
struct LaunchRequest { string name; string symbol; FlywheelMetadata metadata; bytes32 modelHash; bytes32 salt; }
function launchValue() view returns (uint256);
function launch(LaunchRequest request) payable returns (address token, address splitter);
```

| Field | Value |
|---|---|
| `name`, `symbol` | as for Pons |
| `metadata.logoURI` | `https://…` or `ipfs://…`, the URL from `POST /api/launchpad/logo`, or empty |
| `metadata.description` | `description` from prepare |
| `metadata.website`, `metadata.twitter` | `https://…` and `https://x.com/<handle>`, or empty; `telegram` empty |
| `modelHash` | `modelHash` from prepare |
| `salt` | `splitterSalt` from prepare |

The pair (ETH), supply and graduation target are fixed by the factory. To edit the logo or socials later, the payee calls `updateMetadata(metadata)` on the splitter.

## Step 5: register

Right after the receipt:

```
POST /api/launchpad/register
Content-Type: application/json

{ "txHash": "0x…" }
```

No session needed. `200` returns `{ id, status: "bonding", token }`. Retry `404`, `429`, `502` and `503` with backoff (the API's node may not have the receipt yet). `422` is final: the tx didn't launch a launchpad token, wasn't prepared on Surplus, or its params differ from the prepared ones (`error` says which). If registration keeps failing, the token still exists; register it later with the same hash.

## Step 6: follow the launch

- `GET /api/launchpad/launches/<token>` → status, `platform`, splitter, model, `apiModel` once live, hosting paid and owed, inference revenue and your share.
- `GET /api/launchpad/launches?limit=20` → recent launches.
- `GET /api/launchpad/stats` → trading volume (Pons curve, then the v4 pool) across all launches and per launch, all-time and 24h, refreshed every few minutes.
- Web: `https://surplusllm.com/launchpad/<token>`. Trade: `https://www.ponsfamily.com/launchpad/<token>` (Pons) or `https://flywheel.cash/v2/token/<token>` (Flywheel).

| Status | Meaning |
|---|---|
| `bonding` | Trading on the Pons curve, or in the Flywheel pool before its target |
| `graduated` | Pons curve reached 4.2 ETH (liquidity locked in a Uniswap v4 pool), or the Flywheel pool raised its target; model queued for deployment |
| `live` | Served on the Surplus API as `apiModel` (`launch/<org>/<repo>@<sha7>`) |
| `paused` | The hosting vault can't pay the GPU bill; resumes once it holds the bill plus $5 |
| `delisted` | The Pons fee recipient was moved off the splitter, or Pons rescued the reserves |

## Launch credit

A graduated launch no longer gets its own GPU. Its hosting vault share pays for launch credit instead: free daily inference on the models listed in `GET /api/launchpad/launches/<token>/credit` (budget, spent and left per pool, in USD).

- Daily budget: the vault balance over 30 days, capped, half for the builder and half for stakers. If the vault runs low, the Inference Fund tops the launch up to a small daily base.
- Builder: sign in with the launcher wallet and call `POST /api/launchpad/launches/<token>/builder-key` (or use the launch page). The key spends the builder pool on credit models.
- Stakers: send `X-Surplus-Launch: <token>` with a normal Surplus API key of the staking wallet. Without the launch's minimum stake, or once the day's credit is used, the request is paid from the balance.
- Paid requests carry `x-surplus-paid-by: launch-credit`. Old `launch/<org>/<repo>@<sha7>` ids of retired models answer 410 `model_retired`.

## After launch

- Your 30% of creator fees accrues in your splitter (address from `prepare`). `claim()` pulls fees from the Pons escrow (or the WETH Flywheel has credited the splitter) and splits them, `withdraw()` sends your share to the payee (anyone can call both), and the current payee can move it to another address with `setPayee(address)`. The payee starts as the launcher wallet.
- While the model is live, 30% of what callers pay for it on the Surplus API is credited to your wallet's API balance.
- Anyone can top up the hosting vault to keep the model running.
- On Flywheel, the sell side of each trade's fee is ETH right away; the buy side is in your token until Flywheel's operator converts it to ETH, so it reaches the splitter later. `claimable()` on the splitter shows what's ready.

## Script usage

```bash
npm i viem@2
curl -sO https://surplusllm.com/agents/launch.mjs
PRIVATE_KEY=0x… HF_REPO=org/model TOKEN_NAME="Tiny LLM" TOKEN_SYMBOL=TINY node launch.mjs
```

That run signs in, verifies the model and prints the launch params without sending anything. Add `--launch` to send the launch transaction and register it. `PLATFORM=flywheel` launches on Flywheel instead of Pons. Optional env: `TOKEN_LOGO_FILE` (local PNG/JPEG/WebP/GIF up to 512 KB, uploaded for you) or `TOKEN_LOGO` (a link), `TOKEN_WEBSITE`, `TOKEN_TWITTER`, `ROBINHOOD_RPC_URL`. If registration timed out: `node launch.mjs --register 0x<txHash>`.

Human docs: https://surplusllm.com/docs#launchpad
