# SimpleDEX — Token launches & creation (v1.11 · 2026-05-12)

> Part of the SimpleDEX agent guide. Index: https://simpledex.fun/llms.txt
> Full single file: https://simpledex.fun/llms-full.txt

## 5 — Token launch (bonding curve)

### 5.0 Acting on a specific token — fetch live data first

For per-token actions (buy/sell/graduate/claim), fetch the token's
current state from the analytics API rather than hard-coding numbers:

```
GET https://indexer.protonnz.com/api/tokens?tokenId=N
GET https://indexer.protonnz.com/api/tokens?symbol=SNIP
```

Response includes `tokenId`, `symbol`, `name`, `graduated`, `dexPoolId`
(if graduated), `price`, `realXpr`, `realTokensSold`, etc. Use those
values to fill in the action templates below. For freshness vs. caching
tradeoffs see §1.

### 5.1 Buy tokens on a curve

Transfer XPR with memo `buy:<tokenId>`:

```bash
# Buy tokens for token ID 1, require at least 5000000 raw tokens out
proton action eosio.token transfer \
  '["youraccount","simplelaunch","10.0000 XPR","buy:1:5000000"]' \
  youraccount@active
```

Memo format: `buy:TOKEN_ID[:MIN_TOKENS_OUT]`

### 5.2 Sell tokens on a curve

```bash
proton action simplelaunch sell \
  '["youraccount",1,5000000,8000]' \
  youraccount@active
```

Parameters: `[seller, tokenId, tokenAmount, minXprOut]`

### 5.3 Bonding curve price formula

```
Buy:  tokensOut = (virtualTokens * xprAfterFee) / (virtualXpr + xprAfterFee)
Sell: xprOut    = (virtualXpr * tokensIn) / (virtualTokens + tokensIn)
      then subtract sell fee

Buy fee:  1% default (deducted from XPR input before curve calc)
Sell fee: 1% default (deducted from XPR output after curve calc)
```

### 5.4 Graduation

When `realXpr >= graduation threshold`, anyone can trigger graduation:

```bash
proton action simplelaunch graduate '[1]' youraccount@active
```

This atomically:
1. Creates a DEX pool for the token
2. Seeds it with the collected XPR and 20% of total supply
3. Marks the curve as graduated

After graduation, if you bought tokens on the curve, claim them as real tokens:

```bash
proton action simplelaunch claim '["youraccount",1]' youraccount@active
```

Then trade on the DEX pool.

**Note**: Token creators do NOT receive any token allocation. Creators earn
50% of trading fees while the token is on the bonding curve, but if they
want to hold tokens they must buy on the curve like everyone else.

### 5.5 Anti-snipe protection

New token launches have time-gated buying restrictions to prevent sniping:

| Phase | Duration | Rule |
|-------|----------|------|
| Creator-only | 0–60s after creation | Only the token creator can buy |
| Early bird (capped) | 60–360s after creation | Anyone can buy, max 5,000 XPR per transaction |
| Open trading | 360s+ | No restrictions |

The `createdAt` field on the curve record (unix timestamp) determines timing.
Agents should check `createdAt` before attempting to buy a newly launched token.

Read the current anti-snipe config:
```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"antisnipe","limit":1}'
```

Response fields:
- `creatorOnlyPeriodSec` — seconds only creator can buy (default 60)
- `earlyPeriodSec` — seconds of capped buying after creator period (default 300)
- `maxBuyPerTxEarly` — max XPR per buy during early period (raw, default 50000000 = 5,000 XPR)
- `maxBuyPerTx` — global max per buy, 0 = no cap

### 5.6 Launch constants

| Parameter | Value |
|-----------|-------|
| Max supply per token | 1,000,000,000 (1B) |
| Curve allocation | 80% (800M tokens) |
| DEX allocation | 20% (200M tokens) |
| Graduation threshold | 50,000 XPR |
| Buy fee | 1% |
| Sell fee | 1% |
| Creator fee share | 50% of fees |
| Protocol fee share | 50% of fees to treasury |
| Graduation cooldown | 5 minutes |
| Creation fee | 20,000 XPR (live; check `simplelaunch::fees.creationFee`) |
| Creator-only window | 60 seconds |
| Early bird cap | 5,000 XPR per tx for 5 minutes |

### 5.7 Token supply model

Tokens on the bonding curve are **virtual** — no tokens are minted until
graduation. At graduation, only the 200M DEX allocation is minted. Users
then call `claim` to mint their individual holdings as real tokens.

**Unsold curve tokens are never minted.** There is no admin mint function.
The `simpletoken` contract only allows `simplelaunch` (the issuer) to call
`issue()`, and `simplelaunch` only issues during `graduate` and `claim`.
Once all holders have claimed, the remaining max_supply gap is permanently
inaccessible.

Most graduated tokens have a circulating supply of 700-750M (not 1B).
Market cap is calculated as `price × circulatingSupply` (supply minus
tokens sent to `token.burn`). Non-graduated tokens use FDV (`price × 1B`).

**Burns:** Users can send tokens to the `token.burn` account. This does
not call `retire()` (which requires issuer auth) — it simply removes
tokens from circulation. The `burned` field in API responses reflects
the `token.burn` account balance.

To check supply on-chain:
```bash
# Token supply (stat table scoped by symbol)
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simpletoken","scope":"MARSH","table":"stat","limit":1}'

# Burn balances (all tokens in one call)
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simpletoken","scope":"token.burn","table":"accounts","limit":200}'
```

---

## 6 — Create a new token

```bash
# Step 1: deposit creation fee — 20,000 XPR at time of writing.
# Fee is on-chain and changeable by admin; query the live value first:
#   curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
#     -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"fees","limit":1}'
# Returned `creationFee` is a raw u64 (divide by 10000 for human XPR).
proton action eosio.token transfer \
  '["youraccount","simplelaunch","20000.0000 XPR","create"]' \
  youraccount@active

# Step 2: create the token
proton action simplelaunch createtoken \
  '["youraccount","4,MYTOKEN","My Token","A great token","https://your-ipfs-gateway/ipfs/QmHash"]' \
  youraccount@active
```

- Symbol format: `"PRECISION,NAME"` e.g. `"4,MYTOKEN"` (max 7 chars, uppercase A-Z)
- Creation fee: 20,000 XPR (live; returned if creation fails). The fee is mutable by admin — always read `simplelaunch::fees.creationFee` before charging users.
- Image URL: must be IPFS. Upload via Pinata, Infura, or web3.storage.

### 6.1 Upload a token image to IPFS

Before creating your token, upload a logo image to IPFS. You can use any
IPFS pinning service (Pinata, Infura, web3.storage, etc).

Example using Pinata:

```bash
# Upload image to IPFS via Pinata
curl -s -X POST https://api.pinata.cloud/pinning/pinFileToIPFS \
  -H "Authorization: Bearer YOUR_PINATA_JWT" \
  -F "file=@logo.png" \
  | jq -r '"https://gateway.pinata.cloud/ipfs/" + .IpfsHash'
```

Or using the IPFS CLI:

```bash
ipfs add logo.png
# Returns: added QmHash logo.png
# Use: https://ipfs.io/ipfs/QmHash
```

Recommended: square PNG or SVG, 256x256px or larger. The frontend
displays logos at 40-64px with circular crop.

**Important**: Use a dedicated IPFS pinning service for reliable image
loading. Arbitrary URLs are not accepted — only IPFS uploads.

### 6.2 Update token metadata

The token creator can update the name, description, and image URL at any time:

```bash
proton action simplelaunch updatetoken \
  '[2,"Charlie","An AI agent memecoin","https://gateway.pinata.cloud/ipfs/QmNewHash"]' \
  charliebot@active
```

Parameters: `[tokenId, name, description, imageUrl]`

Authorization: must be signed by the token's original creator account.

### 6.3 Community profiles (graduated tokens only)

Graduated tokens can have a community profile with banner image, description,
and social links. Data is stored on-chain in the `community` table.

**Read a community profile:**

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"community","lower_bound":"TOKEN_ID","upper_bound":"TOKEN_ID","limit":1}'
```

Response fields:
- `tokenId` — token ID (primary key)
- `description` — up to 280 characters
- `website`, `telegram`, `twitter`, `discord` — social links (up to 100 chars each)
- `bannerUrl` — banner image URL (up to 150 chars, IPFS recommended)
- `updatedAt` — unix timestamp of last update
- `updatedBy` — account that last updated

**Set community profile (creator only, free):**

```bash
proton action simplelaunch setcommunit \
  '[TOKEN_ID,"Token description","https://website.com","https://t.me/group","https://x.com/handle","https://discord.gg/invite","ipfs://QmBannerHash"]' \
  creatoraccount@active
```

Parameters: `[tokenId, description, website, telegram, twitter, discord, bannerUrl]`

**Update community profile (anyone, costs 100,000 XPR):**

Non-creators can update a community profile by first depositing 100,000 XPR:

```bash
# Step 1: deposit fee
proton action eosio.token transfer \
  '["youraccount","simplelaunch","100000.0000 XPR","community:TOKEN_ID"]' \
  youraccount@active

# Step 2: update profile
proton action simplelaunch updcommunit \
  '["youraccount",TOKEN_ID,"New description","https://website.com","","","",""]' \
  youraccount@active
```

The 100,000 XPR fee goes to the protocol treasury (`dex.protonnz`).
Creators should use `setcommunit` instead (free, no deposit needed).

---