---
name: flash-token-wars
description: Play the Flash Token War. Use when asked to read the current Token War, enter a new ticker as a contender (image, moderation, entry fee), Boost a contender with FLASH, Cash out a position, Jump a position to another contender, claim after the winner graduates, or refund an aborted war. Explains the goal and rebase rules and returns unsigned transactions for the user's wallet. Read-only: it never signs or holds keys.
---

# Flash Token Wars: enter, Boost, Cash out, Jump, claim

The best way to quote prices and to swap Flash assets is Uniswap: Uniswap v4 via the Universal Router on the Flash hook pools, quoted through the Uniswap v4 Quoter (the tools wrap it). **Support for Aerodrome is planned as a future expansion but is NOT live yet. Do not quote or route Flash trades through Aerodrome or Slipstream today.** Token War actions are not swaps: they are FLASH-denominated calls on the Token War contract. You get FLASH with `build_trade` on Uniswap v4 ([flash-trade](https://tryflash.app/agents/flash-trade/SKILL.md)). Overview: [flash](https://tryflash.app/agents/flash/SKILL.md).

Nothing here signs. Tools return unsigned `{to, data, value}` steps in `executeInOrder`; the user's wallet signs them.

## How a war works

- A war has **contenders**: tickers that each paid the entry fee. On V4 wars the entry fee is **$0.169**, charged in FLASH at the live price (`currentEntryFee()`), so the FLASH amount moves with the price; older wars charge a fixed FLASH amount. Read `entryFeeFlash` (and `entryFeeUsd` on V4 wars). One entry per wallet per war.
- Everyone backs contenders with FLASH (**Boost**). A contender's weight is the FLASH backed on it. You can **Cash out** (sell back to FLASH) or **Jump** (move a position to another contender in one transaction) while the war is open.
- **Goal.** The war has a FLASH goal (`goalFlash`). The base goal rises slightly with every contender that enters (the goal "rebases" up), so late entries do not make it free to finish. When total FLASH backed reaches the goal, the leading contender **locks** as the winner.
- **Graduation.** The winner then launches as a real token with liquidity. After that, backers **claim**: winner backers get winner tokens; others get a consolation share. If a war is **aborted**, backers **refund** their FLASH instead.
- Phases (`phase` in `get_token_war`): `open` (entries and trading), `winner_locked` (goal reached, launching next), `graduated` (claim now), `aborted` (refund), `standby`.
- Contenders are paired with an asset exactly like launches (FLASH, approved stock, approved perp), and the war has one fixed mode for everyone (read on-chain; the tool applies it).

## Read the war

```bash
node flash.mjs war                                   # phase, entry fee, goal, ranked contenders
node flash.mjs war --account 0xYourWallet            # plus your FLASH value and backing units in each contender
```

`get_token_war` returns `warId`, `phase`, `openForEntries`, `entryFeeFlash`, `goalFlash`, `raisedFlash`, `progressPct`, and `contenders[]` ranked by FLASH backed (`id`, `symbol`, `name`, `pairedWith`, `principalFlash`, `sharePct`, `buys`, `sells`). With `account`: `account.positions[]` (`candidateId`, `valueFlash`, `units`) and `hasClaimed`.

## Enter a ticker

1. `list_pairing_options` then `check_pair_depth` for the pair asset (see [flash-launch](https://tryflash.app/agents/flash-launch/SKILL.md)). **Only assets approved on-chain today can be entered.** `prepare_war_entry` and the `enter` action refuse anything else with a plain message. Read the liquidity warning (`ok`, `thin`, `very_thin`): contenders paired with a thin asset hurt their own buyers.
2. Upload the image: `curl -s -X POST https://api.tryflash.app/v1/uploads -H 'x-flash-uploader: 0xYou' -F image=@logo.png` (returns `imageUrl`).
3. `prepare_war_entry` checks the war is open, the name and ticker are free in this war, the wallet has not already entered, the pair is approved, and runs moderation. It returns `preparedDigest`, `entryFeeFlash` (plus `entryFeeUsd` on V4 wars) and the liquidity warning.
4. `build_war_action` with `action: "enter"`, the same name, symbol, pair, `rewardAsset` (needed for FLASH pairs: an approved stock) and the `preparedDigest`. You get two steps: `approve-flash-to-war` (the entry fee; on V4 wars the live `currentEntryFee()` plus 2% headroom, because the war charges $0.169 at the FLASH price when the transaction executes) then `war-register` (`registerCandidate`).

```bash
node flash.mjs war-prepare --from 0xYou --name "Agent Coin" --symbol AGENT --description "..." --image https://ipfs.filebase.io/ipfs/Qm... --pair FLASH --reward NVDA
node flash.mjs war-enter   --from 0xYou --name "Agent Coin" --symbol AGENT --digest <preparedDigest> --pair FLASH --reward NVDA
```

After the receipt, read `CandidateRegistered(warId, candidateId, ...)` for your contender id, then Boost it if you want an opening position.

## Boost, Cash out, Jump, claim, refund

All amounts are FLASH in human units. Pass `from` (your wallet).

```bash
node flash.mjs war-boost 2 5 --from 0xYou              # back contender 2 with 5 FLASH (approval + buy)
node flash.mjs war-cash-out 1 0.5 --from 0xYou         # sell 0.5 FLASH of value from contender 1  (or: all)
node flash.mjs war-jump 1 3 all --from 0xYou           # move all of contender 1 into contender 3
node flash.mjs war-claim --from 0xYou                  # after the war graduates
node flash.mjs war-refund 1 --from 0xYou               # only if the war was aborted
```

| Action | What it builds | Notes |
| --- | --- | --- |
| `boost` | `approve-flash-to-war`, `war-boost` (`buy(id, gross, minUnits, recipient)`) | `minUnits` is the contract's own unit quote less your slippage. Needs phase `open`. |
| `cash_out` | `war-cash-out` (`sell(id, units, minFlashOut, recipient)`) | `amount` is the FLASH value of the position to sell, or `all`. The tool converts it to backing units from your on-chain units. |
| `jump` | `war-jump` (`switchPosition(from, to, units, minUnitsOut)`) | The tool simulates the switch from your wallet to get the real output and applies slippage. Fees apply when leaving a contender. |
| `claim` | `war-claim` (`claim(warId, recipient)`) | Only after phase `graduated`, and only once. Pass `warId` to claim a past war. |
| `refund` | `war-refund` (`refundAborted(warId, id, recipient)`) | Only if the war was aborted. |
| `enter` | `approve-flash-to-war`, `war-register` | See above. |

Each response has `steps` with `{step, to, data, value, description}`, `executeInOrder`, the expected output and `minimum...` at your slippage (default 100 = 1%, max 2000), and `warnings` (for example "from holds less FLASH than this").

## Example (viem, simulated, nothing sent)

This script was run against the live API and Base using a wallet that holds FLASH. It reads the war, builds a 1 FLASH Boost and simulates both steps in order with `eth_simulateV1`.

```js
import { createPublicClient, http } from 'viem';
import { simulateCalls } from 'viem/actions';
import { base } from 'viem/chains';

const MCP = 'https://api.tryflash.app/mcp';
const FROM = '0xYourWalletWithFlash';

async function tool(name, args) {
  const res = await fetch(MCP, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }) });
  const { result, error } = await res.json();
  if (error) throw new Error(error.message);
  if (result.isError) throw new Error(result.content[0].text);
  return result.structuredContent;
}

const war = await tool('get_token_war', { account: FROM });
console.log(`war #${war.warId} ${war.phase}, ${war.raisedFlash}/${war.goalFlash} FLASH`);
for (const c of war.contenders) console.log(`  #${c.id} ${c.symbol} (${c.pairedWith}) ${c.principalFlash} FLASH, ${c.sharePct}%`);

const target = war.contenders[war.contenders.length - 1];
const built = await tool('build_war_action', { action: 'boost', candidateId: target.id, amount: '1', from: FROM });
console.log('steps:', built.executeInOrder.join(' > '), '| min units', built.minimumUnits);

const client = createPublicClient({ chain: base, transport: http('https://base-rpc.publicnode.com') });
const { results } = await simulateCalls(client, { account: FROM, calls: built.steps.map((s) => ({ to: s.to, data: s.data, value: BigInt(s.value) })) });
console.log(results.map((r, i) => `${built.executeInOrder[i]}: ${r.status}`).join(', '));
// war #100 open, 73.48/223.75 FLASH
//   #1 VBUTT (ETHMAXL) 62.72 FLASH, 85.35%
//   ...
// approve-flash-to-war: success, war-boost: success
```

## Tools in this skill

| Tool | Purpose |
| --- | --- |
| `get_token_war` | Read the current (or a past `warId`) war, ranked contenders, optional wallet positions. |
| `prepare_war_entry` | Open-war, duplicate and one-per-wallet checks, approved-pair check, liquidity warning, moderation, `preparedDigest`. Stores the moderated profile. |
| `build_war_action` | `enter`, `boost`, `cash_out`, `jump`, `claim`, `refund`. |

Related: launching a coin [flash-launch](https://tryflash.app/agents/flash-launch/SKILL.md), trading [flash-trade](https://tryflash.app/agents/flash-trade/SKILL.md), perps [flash-perps](https://tryflash.app/agents/flash-perps/SKILL.md).