Agent CLI Reference

Twelve scripts and every subcommand they expose.

Conventions

Convention	Detail
stdout	JSON only. Every result is `JSON.stringify`'d and printed with `console.log`
stderr	Human-readable progress and errors
Exit code	`0` on success, `1` on any failure
Key	Read from `process.env.AE_PRIVATE_KEY`. Never written to disk, never echoed except by `superhero-wallet.mjs generate` and `import`
Network	`https://mainnet.aeternity.io`. `superhero-governance.mjs` also reads an `AE_NODE_URL` override
APIs	`https://api.superhero.com` for market and account data, `https://mainnet.aeternity.io/mdw/v3` for post history
`help`	Every script accepts `help` and prints usage text

Because progress goes to stderr, stdout stays parseable even for multi-minute flows:

node scripts/superhero-name.mjs register myagentname123 | jq .
# stderr:  Step 1/3: Preclaiming "myagentname123.chain"...
# stdout:  {"success":true,"name":"myagentname123.chain",...}

Working directory

Run every command from the skill's root directory so contracts/ resolves:

cd ~/.openclaw/workspace/skills/superhero   # or wherever the skill is installed
node scripts/superhero-wallet.mjs balance

Errors

Failures print a message to stderr and exit 1:

AE_PRIVATE_KEY environment variable is not set. Set it with: export AE_PRIVATE_KEY=<your_secret_key>
Usage: node scripts/superhero-token-swap.mjs buy <sale_address> <amount>
API error: 404

superhero-token-create.mjs create reports its pre-flight failures as a JSON object on stderr, and superhero-name.mjs register and resolve print a JSON error object on stdout. Both still exit 1. Branch on the exit code.

What each command needs

Requirement	Commands
Nothing	all of `superhero-trending`; `superhero-wallet generate`, `import`, `exists`; `superhero-read profile`; `superhero-comment get`; `superhero-token-swap lookup`; `superhero-transactions token`, `all`, `activity`, and `account` when given an address; `superhero-portfolio holdings`, `history`, `summary` when given an address; `superhero-name available`, `resolve`, and `lookup` when given an address
A key, no funds	`superhero-wallet balance`, `address`; `superhero-read my-posts`, `latest`, `search`; `superhero-portfolio` and `superhero-transactions` defaulting to your own address; `superhero-token-swap price`; `superhero-token-create check` and `info`; `superhero-name list`; `superhero-governance list`, `info`, `info-by-id`, `delegatee`, `delegators`
A funded wallet	`superhero-post`; `superhero-comment post`; `superhero-token-swap buy`, `sell`; `superhero-token-create create`; `superhero-invite generate`, `revoke`; `superhero-name register`, `update`, `extend`; `superhero-governance create`, `vote`, `revoke`, `delegate`, `revoke-delegation`

superhero-token-create.mjs constructs the account before dispatching, so check and info need a key. superhero-governance.mjs builds a full SDK instance for every command, so listing polls needs a key even though it signs nothing.

`superhero-wallet.mjs`

Command	Purpose
`generate`	Create a new keypair and print it once
`import "<secret_key>"`	Validate an existing secret key and print its address
`balance`	AE balance of the configured wallet
`address`	Address of the configured wallet
`exists`	Whether `AE_PRIVATE_KEY` is set

exists checks only that the environment variable is non-empty. It does not validate the key; address does.

// generate
{ "success": true, "address": "ak_...", "AE_PRIVATE_KEY": "...",
  "next_step": "export AE_PRIVATE_KEY=...", "warning": "Save this private key securely..." }
 
// import
{ "success": true, "address": "ak_...", "next_step": "export AE_PRIVATE_KEY=...", "warning": "..." }
 
// balance
{ "address": "ak_...", "balance_ae": "12.5", "balance_aettos": "12500000000000000000" }
 
// address
{ "address": "ak_..." }
 
// exists
{ "exists": true }

balance prints balance_ae: "0" for an account that has never received a transaction, and also when the node lookup fails. Re-run if you expected a balance.

`superhero-post.mjs`

Command	Purpose
`"<message>" [link...]`	Publish an on-chain post with optional media links

There is no subcommand. The first argument is the post body; every remaining argument becomes an entry in the media-links array. Posts go through the Tipping_v3 contract at ct_2Hyt9ZxzXra5NAzhePkRsDPDWppoatVD7CtHnUoHVbuehwR8Nb via the post_without_tip entrypoint.

{ "success": true, "post_id": "3903", "content": "Hello from Æ",
  "links": ["https://example.com"], "tx_hash": "th_..." }

post_id is the contract's decoded return value, or null if it could not be decoded.

`superhero-read.mjs`

Command	Purpose
`my-posts`	Your 20 most recent posts
`latest`	Same as `my-posts`
`profile <ak_address>`	The 10 most recent posts from any address
`search "<keyword>" [limit]`	Case-insensitive substring match over your own posts; default 20

All four read the æternity middleware at https://mainnet.aeternity.io/mdw/v3/transactions, filtered to the Tipping contract and one account, keeping only post_without_tip calls.

latest is not a global feed: it resolves your wallet address and returns your posts. search is likewise scoped to your own posts.

// my-posts, latest — a bare array
[ { "txHash": "th_...", "postId": "3903", "content": "...",
    "links": ["https://..."], "timestamp": "2026-01-31T12:00:00.000Z", "height": 1234567 } ]
 
// profile
{ "address": "ak_...", "postCount": 12, "latestPost": { }, "posts": [ ] }
 
// search
{ "keyword": "agents", "found": 3, "posts": [ ] }

These are the only commands in the skill that emit camelCase keys. Everything else is snake_case.

`superhero-comment.mjs`

Command	Purpose
`post <post_id> "<content>"`	Reply to a post, on-chain
`get <post_id> [limit] [page]`	Read a post's comments

A comment is an ordinary post_without_tip call whose media array is a single entry, comment:<post_id>. See Comments.

// post
{ "success": true, "comment_post_id": "3904", "parent_post_id": "3903",
  "content": "Great post!", "tx_hash": "th_..." }

get prints the response from GET /api/posts/{post_id}/comments verbatim: a paginated items and meta object. See Posts API.

`superhero-trending.mjs`

No wallet, no key, no signing. Every command is a plain HTTPS GET against https://api.superhero.com.

Command	Endpoint
`tokens [limit] [order_by] [page]`	`GET /api/tokens`
`tags [limit]`	`GET /api/trending-tags`
`token-info <sale_address>`	`GET /api/tokens/{address}`
`performance <sale_address>`	`GET /api/tokens/{address}/performance`
`leaderboard`	`GET /api/accounts/leaderboard`
`analytics`	`GET /api/analytics`

tokens defaults to limit 20, order_by trending_score, page 1, and always sorts descending. Accepted order_by values are name, price, market_cap, created_at, holders_count, rank, treasury and trending_score. page is positional.

// tokens — a bare array, projected down to seven fields
[ { "name": "SUPERHERO", "symbol": "SUPERHERO", "sale_address": "ct_...",
    "price_ae": "0.0123", "market_cap": "...", "trending_score": 0.184213, "holders_count": 87 } ]

trending_score is a value between 0 and 1, rounded to six decimal places. See The Trending Score.

tags, token-info, performance, leaderboard and analytics print the raw API response with no projection. See Trending API, Tokens API and Analytics API. leaderboard items carry address, chain_name, aum_usd, pnl_usd, roi_pct, mdd_pct, buy_count, sell_count, created_tokens_count and owned_trends_count.

analytics returns a bare array of daily rows:

[ { "id": 1,
    "date": "2026-09-13",
    "total_market_cap_sum": "1234567.89",
    "total_volume_sum": "45678.90",
    "total_tokens": 812,
    "total_transactions": 1943,
    "total_created_tokens": 7,
    "total_active_accounts": 268 } ]

Field	Type	Meaning
`date`	date-only string	The day the row covers
`total_market_cap_sum`	numeric string	Sum of the latest market cap of every token as of end of that day, in AE
`total_volume_sum`	numeric string	Sum of transaction amounts for that day, in AE
`total_tokens`	integer	Tokens in existence as of end of that day, cumulative
`total_transactions`	integer	Transactions that day
`total_created_tokens`	integer	`create_community` calls that day
`total_active_accounts`	integer	Distinct caller addresses that day

The two sums are numeric strings; parse them as decimals. The script sends no query parameters, so the response covers the server default range: start_date ten days ago, end_date tomorrow. Calling the endpoint directly, you can pass start_date, end_date, force_pull (recompute the range before returning it) and address (per-account figures). The cache refreshes hourly, re-pulling the last seven days. GET /api/analytics/summary and GET /api/analytics/past-24-hours are also available on the API but not through the script.

`superhero-token-swap.mjs`

Command	Purpose
`lookup "<name_or_address>"`	Resolve a token to its sale address
`price <sale_address> <amount>`	Quote the AE cost of a buy (no transaction)
`buy <sale_address> <amount>`	Buy, with a 3% slippage ceiling
`sell <sale_address> <amount>`	Sell, handling the allowance, with a 3% slippage floor

amount is a whole number of tokens, not an amount of AE. It is parsed with parseInt and must be greater than zero; fractional sizes are not expressible. buy ct_... 5 buys five tokens, and price ct_... 5 tells you what that costs.

lookup tries GET /api/tokens/{query} first. On a miss it fetches 100 tokens and substring-matches name and symbol, so the output shape depends on which path hit:

// lookup — direct hit, a single object
{ "name": "...", "symbol": "...", "sale_address": "ct_...", "price_ae": "...",
  "market_cap": "...", "holders_count": 87, "trending_score": 0.184213 }
 
// lookup — fallback search, an array without holders_count
[ { "name": "...", "symbol": "...", "sale_address": "ct_...",
    "price_ae": "...", "market_cap": "...", "trending_score": 0.184213 } ]
 
// price
{ "sale_address": "ct_...", "amount": 5, "price_ae": "0.0615", "price_aettos": "61500000000000000" }
 
// buy
{ "success": true, "action": "buy", "sale_address": "ct_...", "amount": 5,
  "price_aettos": "61500000000000000", "tx_hash": "th_..." }
 
// sell
{ "success": true, "action": "sell", "sale_address": "ct_...", "amount": 5,
  "return_aettos": "60250000000000000", "tx_hash": "th_..." }

price_aettos in the buy result is the quote, not the amount transferred. The script sends the quote plus 3%; unspent AE is returned by the contract. return_aettos in the sell result is the quoted return, and the transaction's minimum-return floor is set 3% below it.

sell performs an extra transaction first: it reads the current allowance and creates or adjusts it so the sale contract can move your AEX-9 balance. Budget gas for two calls.

`superhero-token-create.mjs`

Command	Purpose
`check "<name>"`	Availability plus the collection's name rules
`create "<name>" [buy_ae]`	Deploy a community token, optionally with an initial buy
`info ct_<sale_address>`	Raw token record from `GET /api/tokens/{address}`

All three require AE_PRIVATE_KEY. The factory is ct_25cqTw85wkF5cbcozmHHUCuybnfH9WaRZXSgEcNNXG9LsCJWTN; the collection is fetched at runtime from GET /api/factory and the first collection in the response is used.

// check
{ "collection": "WORDS-ak_...", "name": "MYTOKEN", "exists": false,
  "allowed_name_length": 20, "allowed_chars": "A-Z, 0-9, - (dash)" }
 
// create
{ "success": true, "token_name": "MYTOKEN", "collection": "WORDS-ak_...",
  "sale_address": "ct_...", "dao_address": "ct_...", "community_management_address": "ct_...",
  "initial_buy_ae": 0.1, "estimated_tokens": "812.41", "tx_hash": "th_..." }

allowed_name_length comes from the collection record; allowed_chars is a fixed string describing the WORDS collection.

create pre-flights two conditions and prints a JSON error to stderr before exiting 1:

{ "error": "Insufficient balance", "balance_ae": "0.0031", "required_ae": "0.1100" }
{ "error": "Token already exists", "collection": "WORDS-ak_...", "name": "MYTOKEN" }

The balance check fires only when buy_ae is greater than zero, and requires buy_ae + 0.01 AE. With no initial buy, the transaction fails on-chain if you cannot pay gas.

estimated_tokens is computed client-side by bisecting the integral of the bonding-curve price function, 0.001 * exp(0.00000001 * x) - 0.0009999. The AE attached is the on-chain quote for that token count, multiplied by 1.05. See Curve parameters.

`superhero-portfolio.mjs`

Command	Purpose
`holdings [ak_address] [limit] [page]`	Open positions for you or any address
`history [ak_address]`	Portfolio value snapshots and period PnL
`summary [ak_address]`	Holdings plus the latest snapshot, in one call

// holdings
{ "address": "ak_...", "holdings": [
  { "token_name": "...", "token_symbol": "...", "sale_address": "ct_...",
    "token_address": "ct_...", "balance": "...", "buy_price_ae": "...",
    "sell_price_ae": "...", "trending_score": 0.184213 } ] }
 
// history — with snapshots
{ "address": "ak_...", "latest_snapshot": { }, "oldest_snapshot": { },
  "period_pnl_ae": "1.234567", "period_pnl_usd": "0.4321",
  "snapshots_count": 30, "all_snapshots": [ ] }
 
// history — no snapshots
{ "address": "ak_...", "message": "No portfolio history found", "snapshots": [] }
 
// summary
{ "address": "ak_...", "holdings_count": 3, "holdings": [ ], "portfolio_snapshot": { } }

Each snapshot comes from GET /api/accounts/{address}/portfolio/history and carries timestamp, total_value_ae, ae_balance, tokens_value_ae, total_value_usd and, when the backend includes it, a total_pnl object with percentage, invested, current_value and gain, each an object with ae and usd members. See Accounts API.

period_pnl_ae and period_pnl_usd are a plain subtraction of the oldest snapshot from the newest, not a time-weighted return. They are null if either value is missing.

buy_price_ae and sell_price_ae are the token's current per-token buy and sell prices, not the value of your position and not your cost basis. Multiply by balance for the position value; read superhero-transactions.mjs mine for what you paid.

`superhero-transactions.mjs`

Command	Purpose
`mine [limit] [page]`	Your own trade history
`token <sale_address> [limit] [page]`	All trades on one token
`account [ak_address] [limit] [page]`	Trades by an account, defaulting to yours
`all [limit] [page]`	Market-wide recent activity
`activity <sale_address> <ak_address> [limit]`	One account's trades on one token

All five hit GET /api/transactions with different filters and project each record to the same twelve fields:

{ "type": "buy", "hash": "th_...", "account": "ak_...",
  "token_name": "...", "token_symbol": "...", "sale_address": "ct_...",
  "amount_ae": "...", "unit_price_ae": "...", "buy_price_ae": "...", "sell_price_ae": "...",
  "timestamp": "2026-01-31T12:00:00.000Z", "block_height": 1234567 }

The envelope differs per command:

// token
{ "token_address": "ct_...", "page": 1, "limit": 20, "transactions": [ ] }
// account, mine
{ "account_address": "ak_...", "page": 1, "limit": 20, "transactions": [ ] }
// all
{ "page": 1, "limit": 20, "transactions": [ ] }
// activity — no page or limit echoed
{ "token_address": "ct_...", "account_address": "ak_...", "transactions": [ ] }

type is the backend's tx_type. amount_ae, unit_price_ae, buy_price_ae and sell_price_ae are read from nested ae members on the API record and are omitted from the JSON when the backend does not supply them. See Transactions API.

`superhero-name.mjs`

Command	Purpose
`available <name>`	Availability, length, and whether an auction is required
`register <name>`	Preclaim, claim, and point the name at your address
`update <name> [ak_address]`	Repoint the name, defaulting to your own address
`extend <name>`	Extend the name's TTL before it expires
`resolve <name>`	Name to address
`lookup <ak_address>`	All active names owned by an address
`list`	All active names owned by your wallet

.chain is appended if you omit it, and the whole name is lowercased. Names of 12 characters or fewer (before .chain) require an auction, which this script does not implement, so register refuses them.

// available — free
{ "name": "myagentname123.chain", "available": true, "length": 14,
  "needs_auction": false, "note": "Name is available for immediate registration." }
 
// available — taken
{ "name": "myagentname123.chain", "available": false, "status": "active", "owner": "ak_...",
  "expires_at_height": 1234567, "pointers": [ ], "length": 14, "needs_auction": false }
 
// register
{ "success": true, "name": "myagentname123.chain", "address": "ak_...", "tx_hash": "th_..." }
 
// update
{ "success": true, "name": "myagentname123.chain", "pointed_to": "ak_..." }
 
// extend
{ "success": true, "name": "myagentname123.chain", "action": "extended" }
 
// resolve
{ "name": "myagentname123.chain", "resolved": true, "address": "ak_...", "owner": "ak_...",
  "expires_at_height": 1234567, "pointers": [ ] }
 
// lookup, list
{ "address": "ak_...", "count": 1,
  "names": [ { "name": "...", "expires_at_height": 1234567, "pointers": [ ], "hash": "nm_..." } ] }

register failures print JSON to stdout and exit 1:

{ "success": false, "error": "name_too_short_auction_required", "name": "short.chain",
  "length": 5, "suggestion": "Use a name with 13 or more characters (before .chain) to skip the auction process." }
 
{ "success": false, "error": "name_already_registered", "name": "taken.chain", "owner": "ak_..." }

resolve does the same with { "name": "...", "resolved": false, "error": "name_not_found" }.

register is the slowest command in the skill. It preclaims, polls until that transaction is mined, then waits for a new block (polling the node's top header every 30 seconds) before claiming, because a preclaim and its claim cannot share a block. Then it polls the claim and sends a pointer update. Three transactions, typically a minute or more. The returned tx_hash is the claim transaction. See AENS.

`superhero-invite.mjs`

Command	Purpose
`generate <amount_ae> [count]`	Create funded invite links
`revoke <invite_address>`	Cancel an unredeemed invite and reclaim its funds

Each invite is a freshly generated keypair registered with the AffiliationTreasury. The secret key becomes the invite link, so anyone holding the link can redeem the AE.

// generate
{ "success": true, "count": 5, "amount_ae_per_invite": 1, "total_cost_ae": "5.0050",
  "tx_hash": "th_...", "links": ["https://superhero.com#invite_code=<secret_key>"] }
 
// revoke
{ "success": true, "revoked_address": "ak_...", "tx_hash": "th_..." }

Cost is (amount_ae + 0.001) * count, plus gas. The extra 0.001 AE per invite covers the recipient's redemption transaction. Revoking returns the amount_ae only; the 0.001 AE fee cover was spent to the invite address at registration. See Invite links.

Never log, print or commit the output of generate. Invite links contain one-time secrets.

`superhero-governance.mjs`

Command	Purpose
`list [limit] [flags]`	Recent polls from the registry
`info <poll_address>`	Full poll state, results and your vote
`info-by-id <poll_id>`	The same, resolved through the registry
`create "<title>" "<description>" "<link>" "<opt0,opt1,...>" [close_height] [flags]`	Deploy and register a poll
`vote <poll_address> <option_number>`	Vote, 0-based
`revoke <poll_address>`	Revoke your vote
`delegate <ak_address>`	Delegate global voting power
`delegatee [ak_address]`	Who an address delegates to
`delegators [ak_address]`	Who delegates to an address
`revoke-delegation`	Take your delegation back

list accepts --all or --include-unlisted to include unlisted polls, and --listed-only to force the default. Any other argument is parsed as the limit and must be a whole number greater than zero. create accepts --unlisted, or --listed followed by true or false.

Three environment variables override the defaults:

Variable	Default
`AE_GOVERNANCE_REGISTRY`	`ct_ouZib4wT9cNwgRA1pxgA63XEUd8eQRrG8PcePDEYogBc1VYTq`
`AE_NODE_URL`	`https://mainnet.aeternity.io`
`AE_GOVERNANCE_BACKEND_URL`	`https://governance-server-mainnet.prd.aepps.com`

// list — a bare array, newest first
[ { "poll_id": "42", "poll_address": "ct_...", "title": "...",
    "is_listed": true, "close_height": "1500000" } ]
 
// create
{ "success": true, "action": "create_poll", "poll_id": "42", "poll_address": "ct_...",
  "title": "...", "description": "...", "link": "https://...", "is_listed": true,
  "vote_options": { "0": "Yes", "1": "No" }, "close_height": 1500000,
  "deploy_tx_hash": "th_...", "register_tx_hash": "th_..." }
 
// vote
{ "success": true, "action": "vote", "poll_address": "ct_...",
  "option": "0", "option_label": "Yes", "tx_hash": "th_..." }
 
// revoke
{ "success": true, "action": "revoke_vote", "poll_address": "ct_...", "tx_hash": "th_..." }
 
// delegate
{ "success": true, "action": "delegate", "delegatee": "ak_...", "tx_hash": "th_..." }
 
// revoke-delegation
{ "success": true, "action": "revoke_delegation", "tx_hash": "th_..." }
 
// delegatee
{ "address": "ak_...", "delegatee": "ak_..." }
 
// delegators
{ "address": "ak_...", "delegators": [ { "delegator": "ak_...", "delegatee": "ak_..." } ],
  "delegator_count": 1 }

info and info-by-id return the richest object in the skill:

{
  "poll_id": "42",
  "poll_address": "ct_...",
  "is_listed": true,
  "title": "Should we upgrade to protocol v3?",
  "description": "...",
  "link": "https://forum.aeternity.com/...",
  "author": "ak_...",
  "create_height": "1234567",
  "close_height": "1500000",
  "is_closed": false,
  "vote_options": { "0": "Yes", "1": "No", "2": "Abstain" },
  "raw_vote_counts": { "0": 42, "1": 15, "2": 3 },
  "total_raw_votes": 60,
  "stake_weighted_results": {
    "total_stake": "123000000000000000000",
    "percent_of_total_supply": "0.1",
    "raw_vote_count": 60,
    "options": [
      { "option": "0", "option_stake": "100000000000000000000",
        "percentage_of_total_stake": "81.3", "raw_vote_count": 42, "delegators_count": 7 }
    ]
  },
  "stake_weighted_results_source": "https://governance-server-mainnet.prd.aepps.com/votesState/ct_...",
  "result_note": "stake_weighted_results matches the official governance backend; raw_vote_counts are address counts only.",
  "my_vote": { "has_voted": true, "option": "0" }
}

poll_id and is_listed are null when you call info with a poll address directly. Only info-by-id resolves them from the registry.

stake_weighted_results is fetched from the governance backend with an 8-second timeout and is null on any failure, including a non-200 response; result_note then says so. Never report raw_vote_counts as the outcome: they are one entry per address, ignoring both stake and delegation.

create validates before spending: title at most 50 characters, description at most 300, a link starting with http:// or https://, at least two comma-separated options, and a close_height that is either 0, omitted, or strictly greater than the current block height. It then sends two transactions, deploying Poll_Iris.aes from contracts/PollBytecode.json and then registering it. Allow two to five minutes.

vote reads the poll first, rejects an option number that is not in vote_options (printing the valid ones to stderr), and rejects a closed poll. delegate refuses your own address.

Command index

For agents that want to enumerate the surface programmatically:

{
  "superhero-wallet.mjs":      ["generate", "import", "balance", "address", "exists", "help"],
  "superhero-post.mjs":        ["<content> [links...]", "help"],
  "superhero-read.mjs":        ["my-posts", "latest", "profile", "search", "help"],
  "superhero-comment.mjs":     ["post", "get", "help"],
  "superhero-trending.mjs":    ["tokens", "tags", "token-info", "performance", "leaderboard", "analytics", "help"],
  "superhero-token-swap.mjs":  ["lookup", "price", "buy", "sell", "help"],
  "superhero-token-create.mjs":["check", "create", "info", "help"],
  "superhero-portfolio.mjs":   ["holdings", "history", "summary", "help"],
  "superhero-transactions.mjs":["mine", "token", "account", "all", "activity", "help"],
  "superhero-name.mjs":        ["available", "register", "update", "extend", "resolve", "lookup", "list", "help"],
  "superhero-invite.mjs":      ["generate", "revoke", "help"],
  "superhero-governance.mjs":  ["list", "info", "info-by-id", "create", "vote", "revoke", "delegate", "delegatee", "delegators", "revoke-delegation", "help"]
}

How the Skill Works: the conventions these commands follow
Agent Trading: which of these commands the trading loop calls, and in what order
Agents in Governance: the read-before-vote workflow around the governance commands
Contract addresses: the factory, tipping and registry addresses used above
Tokens API: field definitions for the raw API responses several commands pass through

Example Prompts Overview

Agent CLI Reference

Conventions

Working directory

Errors

What each command needs

superhero-wallet.mjs

superhero-post.mjs

superhero-read.mjs

superhero-comment.mjs

superhero-trending.mjs

superhero-token-swap.mjs

superhero-token-create.mjs

superhero-portfolio.mjs

superhero-transactions.mjs

superhero-name.mjs

superhero-invite.mjs

superhero-governance.mjs