# Build on Soon

> Soon (soonlaunchpad.fun) is a proof-of-work token launchpad on the Internet Computer (ICP). Every token, curve, rig and post lives in a public canister, so anyone can build sites, games, bots and tools around Soon tokens without asking permission. This guide is for people and AI builders (Caffeine, Claude, ChatGPT, Cursor, Lovable, Bolt, v0, your own code). To trade, launch or mine as an agent with its own key, read https://soonlaunchpad.fun/llms.txt instead.

## Ground rules for anything you build

- Reading is free and needs no key: every read below is a query call, answered in milliseconds.
- Users sign with their own wallet (Internet Identity, Plug, OISY or any ICRC wallet). Never ask anyone for a seed phrase, private key or password, and never hold users' funds in your app.
- Money only moves by ICRC-2 approve-then-pull: the user approves an exact amount to a Soon canister, which pulls it. Show the user what they approve.
- Don't present your app as Soon or as official. Say "built on Soon" or "for $TICKER". See https://soonlaunchpad.fun/terms (Trademark Guidelines).
- Soon is in beta. Don't promise prices or returns, and label any illustrative data.

## Canisters (ic)

- Factory: 3jz7z-jqaaa-aaaab-ag6kq-cai. It knows every token. `config()` lists every canister id and number, `markets(sort, offset, limit, base)` lists tokens, `search(text)` finds them by name, ticker or id, `launch_of(market)`, `market_of_ledger(ledger)`, `markets_of(creator)`, `rigs_of(owner)`, `events(n)` (live feed of launches, trades, blocks), `stats()`, `buckets(from_ns, to_ns)` (hourly history), `prices()` (USD per base token), `names(principals)` (display names).
- Market (one per token): `info()` (price, curve progress, phase, supply, mining state), `trades(n)`, `candles(hourly, since_ns)`, `miners()`, `mining_info()`, `quote_buy(amount)`, `quote_sell(amount)`, `locked_of(principal)` (mined rewards waiting for listing).
- Ledger (one per token): DFINITY's ICRC-1/ICRC-2 ledger, 8 decimals, fee 0.0001. `icrc1_balance_of`, `icrc1_total_supply`, `icrc1_metadata`, `icrc2_approve`, `icrc1_transfer`. Any ICRC tool, wallet or explorer works with it.
- Rig (one per miner canister): `status()`; its owner can `set_market`, `set_power`, `set_paused`.
- Social: phejn-2yaaa-aaaab-ahaaa-cai. `feed(before, n, only)` (every token; only = "posts" or "moments"), `thread(market, before, n)`, `hot(n)`, `recent_trades(before, n)`, `trades_of(principal, before, n)`, `top_voices(days, n)`, `author_stats(principal)`, `follower_count`, `activity(days)`.
- Token logo: `https://<market>.raw.icp0.io/logo`. Token page: `https://soonlaunchpad.fun/t/<market>`.
- Candid (the exact types): https://soonlaunchpad.fun/did/factory.did, /did/market.did, /did/rig.did, /did/social.did. It is also public metadata on every canister: `dfx canister --network ic metadata <id> candid:service`. Generate typed bindings with `didc bind market.did -t ts` (or -t js, rs, mo).

## Read a token from any website (JavaScript)

```js
import { HttpAgent, Actor } from "@dfinity/agent";
import { Principal } from "@dfinity/principal";

const agent = await HttpAgent.create({ host: "https://icp-api.io" });
const ledgerIdl = ({ IDL }) => {
  const Account = IDL.Record({ owner: IDL.Principal, subaccount: IDL.Opt(IDL.Vec(IDL.Nat8)) });
  return IDL.Service({
    icrc1_balance_of: IDL.Func([Account], [IDL.Nat], ["query"]),
    icrc1_symbol: IDL.Func([], [IDL.Text], ["query"]),
  });
};
const ledger = Actor.createActor(ledgerIdl, { agent, canisterId: "<token ledger id>" });
const balance = await ledger.icrc1_balance_of({ owner: Principal.fromText("<user principal>"), subaccount: [] });
// balance is in 1e-8 units: Number(balance) / 1e8 tokens. Gate a page, a level or a role on it.
```

The same pattern works from Node, Deno, Bun, a Cloudflare Worker or a browser on any host (the ICP gateway answers cross-origin requests). Other languages: `ic-agent` (Rust), `ic-py` (Python), `agent-go`, Motoko or Rust canisters by inter-canister call.

## Let users act (they sign, not you)

- Buy: base ledger `icrc2_approve({ spender: market, amount: amount + fee })` → `market.buy({ amount, min_tokens_out })`. Get `min_tokens_out` from `quote_buy` minus your slippage.
- Sell: token ledger `icrc2_approve({ spender: market, amount })` → `market.sell({ amount, min_base_out })`.
- Mine: ICP ledger `icrc2_approve({ spender: factory, amount: e8s + 10_000 })` → `factory.spawn_rig({ e8s, power, market })` (from 1 ICP, power 1 to 10; 1% mining fee, half to the token's creator). Refuel with `factory.top_up(rig, e8s)` after the same kind of approval.
- Mine with TCYCLES: Cycles Ledger `icrc2_approve({ spender: factory, amount: cycles + 200_000_000 })` → `factory.spawn_rig_with_cycles({ cycles, power, market })` (from 2T cycles) or `factory.top_up_with_cycles(rig, cycles)` (from 0.1T). Same 1% fee, paid in TCYCLES; the rest goes from the user's Cycles Ledger account straight to the rig.
- Post: `social.post` signed by the user. Rate limits apply per person.
- Or link out: `https://soonlaunchpad.fun/t/<market>` opens the token with trading and mining ready, and needs nothing from your app.

## Earn from the trades you bring (referrals)

Every curve buy and sell can name a `referrer`: the principal of the app, bot, game or person that brought the trader. The token's market pays the referrer 0.2% of the trade, out of Soon's half of the 1% fee (the creator's 0.5% is untouched), in the token's base, every six hours with the other fees. Nothing to register and nothing to claim.

- From your own code: `market.buy({ amount, min_tokens_out, referrer: [yourPrincipal] })` and `market.sell({ amount, min_base_out, referrer: [yourPrincipal] })`.
- From a link: any `https://soonlaunchpad.fun` link with `?ref=<yourPrincipal>` (say `https://soonlaunchpad.fun/t/<market>?ref=<you>`) makes that visitor's curve trades for the next 30 days pay you.
- Buying for someone else (a bot or game making the buy with funds the user gave it): add `recipient: [{ owner: user, subaccount: [] }]`, and the tokens and any refund go straight to them.
- Check what you've earned on a token: `market.referral_of(yourPrincipal)` → `{ owed, earned }`. Anyone can push a payout early with `market.claim_referral_fees(yourPrincipal)`; it can only go to you.
- Use any principal you control as the referrer: a canister, or a wallet. Pointing it at yourself works too (it's a 0.2% rebate on your own trades).

## A Telegram bot (template)

Soon has its own official bot (add it from any token page). Yours can be different: a bot for one token's community, a game, a sniper-free launch feed. The template at https://soonlaunchpad.fun/telegram-bot-template.zip (Node, no server state, about 150 lines) posts a token's buys to your group and answers /price, and every button carries your `?ref=`, so trades it brings pay you. Run it anywhere Node runs: `BOT_TOKEN=… CHAT_ID=… MARKET=… REFERRER=… node bot.mjs`.

## Ideas

- A site for your token: live price, curve progress, holders' balance check, latest trades and chat (`market.info`, `market.trades`, `social.thread`).
- Holder-gated anything: a page, a Discord or Telegram role, a game level unlocked by holding (`icrc1_balance_of`).
- Games that pay or spend your token: the player approves, your canister pulls, scores live on-chain.
- Mining tools: a rig manager, alerts when fuel runs low, a "best to mine" board (`rigs_of`, `rig.status`, `market.mining_info`).
- Bots: post big buys, new launches or listings to X, Telegram or Discord (`factory.events`, `social.recent_trades`), with your `?ref=` on every link so the trades they bring pay you.
- Dashboards and leaderboards: top miners, top voices, volume over time (`market.miners`, `social.top_voices`, `factory.buckets`).

## Cycles by card (for you, and for your users)

- Canisters run on cycles. Buy them with a card from a terminal: `icp cycles buy --amount 10 -n ic` (icp-cli 1.7.0 or later); they land in your identity's Cycles Ledger account.
- Top up any canister by card, no sign-in, $5–$100: `https://www.cyclepay.org/c/<canister id>/<usd>`.
- Put cycles in anyone's wallet by card: `https://www.cyclepay.org/b/<principal>/<usd>`. On Soon that balance is TCYCLES (Cycles Ledger `um5iw-rqaaa-aaaaq-qaaba-cai`, 12 decimals), a base token on Soon: your users can spend it on TCYCLES-priced tokens or fuel rigs with it (`spawn_rig_with_cycles`, `top_up_with_cycles`). Each payment is a separate purchase: tell users to pay once.
- CyclePay is a DFINITY Foundation service (card payments by Stripe). Never handle card details yourself; hand the link to the person paying. Guide for agents: https://www.cyclepay.org/llms.txt

## Deploy

- On ICP (recommended, the whole stack on-chain): Caffeine (describe the app, it builds and deploys to ICP), `dfx deploy` or `icp-cli` with an asset canister, Juno, or any ICP frontend host. Your app's canisters can call Soon's directly.
- Anywhere else: Vercel, Netlify, Cloudflare, your own server. Reads go through the ICP gateway with an agent library as above.

Share what you build: @soonlaunchpad on X.