Skip to content

tokenization.md

Latest commit

 

History

History
230 lines (161 loc) · 13.3 KB

tokenization.md

File metadata and controls

230 lines (161 loc) · 13.3 KB
Raw

Tokenization

The acp agent tokenize command launches a token for the active agent.

Prerequisites

  1. An active agent is set — run acp agent use if you haven't.
  2. A signer is registered for the active agent — run acp agent add-signer if you haven't. tokenize will refuse to run without a signer.
  3. The agent wallet holds enough of the venue's currency: VIRTUAL on the Virtuals launchpad, to cover the launch fee plus any pre-buy; the quote asset on Occupy, to cover a pre-buy (there is no launch fee, so with no pre-buy the wallet needs none of it). Either way the wallet also needs a gas token: Gas is paid from the agent wallet in an ERC-20 — USDC, USDT or VIRTUAL, whichever it holds — rather than in ETH. So the wallet needs no ETH, but it is not true that it needs nothing: without a small balance of one of those three the launch is refused with "Not enough balance to cover the network fee".. Either way the agent spends from its own wallet.
  4. The agent wallet has enough ETH to cover gas fees for the on-chain transactions, unless gas is sponsored for it.

Chain selection

The available chains come from the EVM provider attached to the active agent. You can:

  • Pass --chain-id <id> to pick explicitly. Must be one of the provider's supported chains.
  • Omit it to be prompted (or auto-selected when only one chain is available).

Anti-sniper protection

Anti-sniper applies a temporary transfer tax to newly launched tokens to discourage sniper bots from buying in the first seconds/minutes.

Value Label Duration Venue
0 None Off Both
1 60 seconds Default Both
2 98 minutes Extended Virtuals only

Occupy offers only 0 or 1; 2 is a Virtuals launchpad option and is rejected on Occupy.

Pre-buy

At launch, the agent wallet can atomically buy some of its own freshly minted agent token in the same preLaunch transaction by spending extra VIRTUAL on top of the launch fee.

  • --prebuy <virtuals> — amount of VIRTUAL tokens to spend at launch (whole units, e.g. 100 = 100 VIRTUAL).
  • Omitted or 0 → no pre-buy.
  • Before sending any transaction, the CLI checks that the agent wallet holds at least launchFee + prebuy VIRTUAL and aborts with a clear message if not.

Capital Formation (ACF)

ACF is an optional boolean toggle at launch. When enabled:

  • The on-chain launch fee is higher (an ACF surcharge is added on top of the base fee). The CLI shows the total fee before proceeding.
  • Additional features are auto-enabled (dev allocation tokenomics, sell wall).
  • Pre-buy is capped at ≤50% of the LP. If you exceed this with --prebuy, the transaction will fail and the CLI will show a hint.

No other user input is required — it's a pure yes/no switch.

60 Days Experiment

A reversible launch mode for early-stage founders to test product/market fit over a 60-day commitment window. Enable with --60-days.

  • No launch-fee impact.
  • Pre-buy cliff: pre-purchased tokens follow a 60-day cliff (instead of the standard 1-month cliff) when this mode is on.
  • Compatible with --acf and --prebuy. Both can be combined with --60-days.
  • Growth Allocation Pool is web-UI only. The Growth Allocation Pool sub-feature (allocate 0–5% of team stack as a separate pool for USDC deposits at a target FDV; auto-enables ACF) is not exposed in the CLI. To launch with a Growth Pool, use the web app at app.virtuals.io → create agent → enable the 60 Days Experiment toggle → check "I want to include Growth Allocation Pool".

It's a pure yes/no switch — no other CLI input required.

Airdrop Distribution

At launch, you can allocate 0–5% of the agent token supply to veVIRTUAL holders. Recipients are derived post-launch from a veVIRTUAL snapshot - no recipient list is required at CLI time.

  • --airdrop-percent <percent> — decimal in [0, 5], e.g. 1.25, 2.5. Omitted or 0 → no airdrop.
  • No launch-fee impact.

Robotics Launch

Marks the virtual as an Embodied (robotics-capable) agent and makes it eligible for Eastworld — the Virtuals robot fleet and physical testing environment. A "Robotics Launch" badge is shown on the agent's detail page.

  • --robotics — presence-only boolean flag. Omitted → off.
  • No launch-fee impact.
  • Eastworld onboarding is post-launch. Once the flag is set, use app.virtuals.io (or the partnerships team) to complete Eastworld onboarding. There is no CLI command for the physical onboarding flow.
  • Compatible with all other flags (--acf, --60-days, --airdrop-percent, --prebuy, --anti-sniper). No mutual exclusions apply.

Occupy launchpad

--launchpad occupy launches on Occupy instead of the Virtuals launchpad. Everything above (ACF, 60 Days, airdrop, Robotics) is Virtuals-specific and is rejected rather than silently ignored when combined with --launchpad occupy.

Occupy differs in three ways that matter at the CLI:

  • Single-phase and free. One launch call mints the token, opens the Uniswap v4 pool and settles the pre-buy. There is no launch fee, so the agent wallet needs no VIRTUAL — only gas, which is sponsored for ACP agent wallets.
  • The curve is quoted in a tokenized equity, not VIRTUAL. --quote-token picks it, and it is required — there is no default, because the choice decides which stock your token trades against. WETH, USDC and VIRTUAL are not allow-listed. The backend reads AssetConfig before creating anything and rejects an asset that is not allowed.
  • --quote-token takes an address, not a ticker. A ticker would have to be resolved against the full allow-list, and AssetConfig offers only a point lookup — enumerating it means an archive-depth log scan that public RPCs refuse. So the list is published rather than fetched: look the asset up at https://os.virtuals.io/agent-identity/token/overview#occupy-quote-assets and pass its address.
  • Decimals vary per asset. The share tokens are 8-decimal, wtFGI is 18. --prebuy 5 means 5 units' worth and the CLI reads the token's own decimals() to convert it — assuming 18 against an 8-decimal asset would overspend by a factor of 10^10.
  • A pre-buy is denominated in the quote asset, so --prebuy on Occupy requires --quote-token.

Occupy runs on EVM chains only; Solana launches go through the Virtuals launchpad.

Flag Default Notes
--name <name> the agent's name Token name on-chain. Occupy names the token independently of the agent
--quote-token <address> required, no default Address of the asset the curve is priced against. Listed at EconomyOS
--pool-fee <fee> 1% The trading fee every buy and sell pays. One of 1%, 2%, 3% — pass 1, 2, 3 or 10000, 20000, 30000
--take-fees off Pay your 30% creator share of that fee to the agent wallet. Off leaves it in the pool
--no-thicken-liquidity — Alias for --take-fees — the on-chain name for the same switch
--anti-sniper <0|1> 1 0 off, 1 60 seconds. The contract accepts 2 (98 min) but Occupy does not offer it, so the API rejects it
--prebuy <amount> none In quote-token units, not VIRTUAL. Requires --quote-token

Addresses below come from the published allow-list: https://os.virtuals.io/agent-identity/token/overview#occupy-quote-assets

# Launch on Occupy, priced against NVIDIA
acp agent tokenize --launchpad occupy --chain-id 8453 --symbol MYTOKEN \
  --quote-token 0xb20000000000000000000078ee7ce2fE4908108C

# Name the token something other than the agent's name
acp agent tokenize --launchpad occupy --chain-id 8453 --symbol MYTOKEN \
  --name "My Token" --quote-token 0xb20000000000000000000078ee7ce2fE4908108C

# No anti-sniper protection
acp agent tokenize --launchpad occupy --chain-id 8453 --symbol MYTOKEN \
  --quote-token 0xb20000000000000000000078ee7ce2fE4908108C --anti-sniper 0

# 3% pool fee, no liquidity thickening
acp agent tokenize --launchpad occupy --chain-id 8453 --symbol MYTOKEN \
  --quote-token 0xb2000000000000000000001e800a7f5189430cD0 --pool-fee 30000 --no-thicken-liquidity

# Pre-buy 5 shares' worth of the quote asset at launch
acp agent tokenize --launchpad occupy --chain-id 8453 --symbol MYTOKEN \
  --quote-token 0xb20000000000000000000078ee7ce2fE4908108C --prebuy 5

--pool-fee takes one of three rates — 1%, 2% or 3% — as either a percentage or the contract's own unit (hundredths of a bip, where 1% = 10000):

You want Pass either Not
1% (default) 1 or 1% 10000 also works
2% 2 or 2% 20000 also works
3% 3 or 3% 30000 also works

There is nothing in between. 1.5% / 15000 is rejected, not rounded — Occupy offers exactly these three rates. 100, 200 and 1000 are not 1%, 2% and 0.1%; they are below the contract's floor and rejected too.

Who gets the trading fee

--pool-fee sets the fee every buy and sell of your token pays, forever — 1%, 2% or 3% — 1% by default. It is the only trading cost the launch actually sets.

That fee is then split three ways by the launchpad, globally — you don't choose the split, and it is not in the launch call. Read live from AssetConfig on Base:

Share Bips Goes to
creatorBips 3000 30% — you, the creator
taxVaultBips 4000 40% — the quote asset's tax vault
protocolBips 3000 30% — the protocol

--take-fees decides what happens to your 30%. It is off by default, and off means your cut is left in the pool as permanent liquidity rather than paid out. Pass --take-fees to have it paid to the agent wallet as it accrues.

# Default: your 30% cut stays in the pool, deepening liquidity forever
acp agent tokenize --launchpad occupy --symbol MYTOKEN --quote-token 0xb200…108C

# Take the cut instead — paid to the agent wallet as trades happen
acp agent tokenize --launchpad occupy --symbol MYTOKEN --quote-token 0xb200…108C --take-fees

--no-thicken-liquidity is the same switch under its on-chain name (thickenLiquidity), kept because that is what the contract and the API call it. Occupy's own UI presents it the way --take-fees does.

CLI usage

acp agent tokenize [--chain-id <id>] [--symbol <symbol>] [--anti-sniper <0|1|2>] [--prebuy <virtuals>] [--acf] [--60-days] [--airdrop-percent <percent>] [--robotics] [--configure]
acp agent tokenize --launchpad occupy --quote-token <address> [--chain-id <id>] [--symbol <symbol>] [--name <name>] [--pool-fee <fee>] [--take-fees] [--anti-sniper <0|1|2>] [--prebuy <amount>]
  • --chain-id <id> — chain to launch on. Restricted to what the provider supports.
  • --symbol <symbol> — token symbol (uppercased). Prompted if omitted.
  • --anti-sniper <0|1|2> — set directly (0 or 1 only on Occupy). Respected with or without --configure.
  • --prebuy <virtuals> — VIRTUAL tokens to spend at launch. Respected with or without --configure.
  • --acf — enable Capital Formation. Respected with or without --configure.
  • --60-days — enable 60 Days Experiment mode. Respected with or without --configure.
  • --airdrop-percent <percent> — airdrop allocation to veVIRTUAL holders (0–5). Respected with or without --configure.
  • --robotics — mark as a Robotics (Eastworld-eligible) launch. Respected with or without --configure.
  • --launchpad <virtuals|occupy> — launchpad to launch on. Defaults to virtuals. See Occupy.
  • --configure — interactive pickers for anti-sniper, pre-buy, ACF, 60 Days Experiment, airdrop, and Robotics (blank / N to skip). Skipped for values already passed via flags.

Without --configure, the defaults below apply automatically — the CLI will not prompt for these options. Only --chain-id and --symbol are prompted when omitted.

  • Defaults: anti-sniper 1 (60 seconds), no pre-buy, ACF off, 60 Days Experiment off, no airdrop, Robotics off.

Examples

# Default (60s anti-sniper, no pre-buy, no ACF), chain picked interactively if multiple
acp agent tokenize

# Launch on a specific chain
acp agent tokenize --chain-id 8453 --symbol MYTOKEN

# Disable anti-sniper
acp agent tokenize --anti-sniper 0

# Pre-buy 100 VIRTUAL of the new token
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --prebuy 100

# Enable Capital Formation
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --acf

# ACF + pre-buy (stay ≤50% of LP)
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --acf --prebuy 50

# Enable 60 Days Experiment
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --60-days

# 60 Days Experiment + ACF + pre-buy
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --60-days --acf --prebuy 50

# Airdrop 2.5% of supply to veVIRTUAL holders
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --airdrop-percent 2.5

# Airdrop + pre-buy (airdrop reduces pre-buy headroom)
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --airdrop-percent 1 --prebuy 50

# Robotics Launch (Eastworld-eligible)
acp agent tokenize --chain-id 8453 --symbol MYTOKEN --robotics

# Pick anti-sniper, pre-buy, ACF, 60 Days Experiment, airdrop, and Robotics interactively
acp agent tokenize --configure