# Axiom Protocol — Agent Skill (Axiom CLI) This skill tells AI agents how to interact with Axiom prediction markets through the Axiom CLI. ## Primary Rule Agents should prefer the Axiom CLI for supported market operations. Direct contract interaction is allowed, but it is a fallback path and usually provides less data than the CLI because the CLI also uses backend API reads. The preferred workflow is still to use the CLI for: - market discovery - market metadata and outcome labels - prediction quotes - buying positions - claiming winnings - rewards inspection and reward claims - funding instructions - profile inspection If an agent uses contracts directly, it should explain that this path may have reduced visibility into market metadata, historical data, profile statistics, destination-tag flows, and backend-derived unclaimed winnings. If the CLI is unavailable in the environment, the agent should say so clearly. It may still proceed with direct contract interaction when that is feasible, while noting the reduced data coverage. --- ## Scope (Hard Rules) The agent may perform supported Axiom operations. The CLI is preferred, but direct contract interaction is allowed when needed: 1. Configure the CLI 2. Create or import wallets 3. Register a wallet with Axiom 4. Discover markets 5. Read market metadata and outcome labels 6. Quote predictions 7. Buy market positions 8. Inspect profile stats, positions, and unclaimed winnings 9. Inspect rewards progress and claim daily, weekly, or epoch rewards 10. Claim a single market or batch claim all unclaimed winnings 11. Show funding instructions for XRPL relay or direct XRPL EVM funding The agent must not perform privileged or operator-only actions, including: - market creation - admin cancellation - bootstrap or operator flows - contract upgrades - implementation registration If asked to perform restricted actions, the agent must refuse and explain that those flows are not supported CLI operations. --- ## CLI Prerequisites - Network: XRPL EVM - Mainnet chain ID: `1440000` - Testnet chain ID: `1449000` - Mainnet RPC: `https://rpc.xrplevm.org` - Testnet RPC: `https://rpc.testnet.xrplevm.org` The CLI expects two categories of connectivity: 1. Backend API reads for market discovery, profile data, destination tags, and unclaimed winnings 2. XRPL EVM RPC access for transaction submission and live on-chain reads that the CLI performs internally ## Build Axiom CLI From Source Axiom CLI is the public command-line interface for Axiom users. It lets users create or import wallets, register for funding, browse markets, place predictions, inspect profiles and positions, and claim winnings from the terminal. Public source repository: - `https://github.com/Gen3Games/axiom-cli` - `https://github.com/Gen3Games/axiom-cli/releases/latest` for the latest prebuilt release - `https://github.com/Gen3Games/axiom-cli/releases` to browse all published versions Build steps: 1. `git clone https://github.com/Gen3Games/axiom-cli` 2. `cd axiom-cli` 3. `go mod tidy` 4. `go build -o axiom ./cmd/axiom` 5. `./axiom --help` Run without creating a binary: - `go run ./cmd/axiom --help` If a prebuilt binary is preferred, download the latest release or pick any published version from the releases page instead of building from source. Recommended setup flow: ```text cd axiom-cli go build -o axiom ./cmd/axiom ./axiom config set --api-url ./axiom config set --rpc-url https://rpc.xrplevm.org ./axiom config set --xrpl-rpc-url https://s1.ripple.com:51234 ``` For automation and scripting, prefer JSON output: ```text axiom --json ``` For headless environments without an OS keychain, use the encrypted file-backed secret store: ```text AXIOM_CLI_SECRET_STORE=file AXIOM_CLI_SECRET_PASSPHRASE= ``` --- ## Agent Playbook ### 1. Create or import a wallet Create a new XRPL EVM wallet: ```text axiom wallet create ``` Import an existing EVM wallet: ```text axiom wallet import --private-key ``` Optional XRPL wallet support for relay funding: ```text axiom wallet xrpl-create axiom wallet xrpl-import --seed ``` Inspect wallet metadata and balances: ```text axiom wallet show axiom wallet balance ``` ### 2. Register the wallet with Axiom ```text axiom auth register ``` This registers the wallet and retrieves the destination tag used for Axiom funding flows. ### 3. Get funding instructions Show relay funding information: ```text axiom funding info axiom funding bridge ``` Optionally prefill a relay amount: ```text axiom funding bridge --amount 25 ``` For direct XRPL EVM funding: ```text axiom funding direct --to --amount ``` ### 4. Discover markets through the CLI Use the backend-backed market list instead of scanning chain logs manually: ```text axiom markets list axiom markets list --status open axiom markets list --status resolved axiom markets list --category hourly axiom markets list --search XRP axiom markets list --spot-prices ``` The default `axiom markets list` behavior is to show all open markets. For CLI market discovery, `open` is the primary user-facing status and `resolved` is the supported historical view. Get a single market by slug or address: ```text axiom markets get ``` Important guidance: - prefer market slugs or IDs when available - use `markets get` to retrieve outcome labels - do not hardcode labels like `Yes` and `No` unless the CLI response confirms them If the CLI is unavailable, agents may fall back to direct contract discovery and reads, but should note that this can miss backend-only metadata and may produce a less complete market view. ### 5. Quote before buying Agents should quote first, then reuse the returned `minShares` suggestion when buying. ```text axiom predict quote --label "Higher" --amount 15 axiom predict quote --outcome 1 --amount 15 ``` The quote command provides: - current spot price - average entry price - post-trade spot price - base shares - weighted shares - suggested `minShares` - gross payout estimate ### How Time Bonus Works Agents should treat `weighted shares` as the payout-relevant quantity, not just `base shares`. The CLI quote output exposes both: - `Base Shares`: shares from the pool math alone - `Time Bonus`: the early-entry multiplier - `Weighted Shares`: `Base Shares × Time Bonus` Core rules: 1. If a market has time bonus enabled, earlier buys get a higher multiplier. 2. The multiplier decays linearly from the configured `maxTimeBonus` at market open down to `1.0x` at `betsClose`. 3. If `maxTimeBonus` is `0`, the bonus is disabled and weighted shares equal base shares. 4. Final payout on the winning outcome is based on your share of total weighted shares on that outcome, not raw stake size alone. Reference formula used in shared Axiom math: ```text timeBonus = maxTimeBonus - ((maxTimeBonus - 1.0) * elapsed / bettingDuration) weightedShares = baseShares * timeBonus ``` Practical agent guidance: 1. Quote before buying so the current time bonus is explicit. 2. Do not assume the same XRP amount receives the same weighted shares later in the market. 3. When comparing entries across time, compare `weightedShares`, `average entry price`, and `gross payout estimate` together. 4. If two buys have similar stake amounts but different timestamps, the earlier buy can still have a meaningfully larger payout claim because of higher weighted shares. ### 6. Buy through the CLI After quoting, place the prediction with the CLI: ```text axiom predict buy --label "Higher" --amount 15 --min-shares axiom predict buy --outcome 1 --amount 8 --wait ``` The CLI handles the correct execution path internally, including: - market resolution by slug or address - mapping outcome labels to indexes - live market reads - native XRP market buys - ERC20 approval plus buy flows when needed Agents should prefer this CLI path. Direct contract execution is allowed as a fallback when the CLI is unavailable or unsuitable, but the agent should note that it may have less supporting data. ### 7. Inspect state ```text axiom profile show axiom profile update --display-name axiom profile update --avatar-url axiom profile positions axiom profile unclaimed ``` These commands are the preferred way to inspect activity and pending winnings. ### 8. Inspect and claim rewards through the CLI ```text axiom rewards show axiom rewards claim daily axiom rewards claim weekly 77 axiom rewards claim epoch 12 ``` Use these commands for CLI-authenticated rewards flows instead of trying to reconstruct rewards state from contracts alone. ### 9. Claim winnings through the CLI Claim a single market: ```text axiom claim market ``` Claim all currently unclaimed winnings returned by the backend: ```text axiom claim batch axiom claim batch --wait ``` The batch command uses the canonical Axiom utility flow internally. Agents should use the command rather than assembling a raw batch claim transaction. --- ## Automation Rules For agent automation, prefer: - `axiom --json markets list --status open` - `axiom --json rewards show` - `axiom --json markets get ` - `axiom --json profile show` - `axiom --json profile unclaimed` Automation guidance: 1. Use `--json` whenever the output will be parsed by a tool or agent 2. Prefer labels only after reading them from `markets get` 3. Run `predict quote` before `predict buy` for nontrivial trades 4. Use `--wait` when the workflow requires confirmed settlement before the next step 5. Surface CLI errors directly, and if falling back to contract-level logic, explain that the result may have less complete data than the CLI path --- ## Safety Rules Before buying: 1. Confirm the CLI is pointed at the intended API and RPC URLs 2. Confirm the market exists through `markets get` 3. Confirm the requested outcome label or index is valid 4. Prefer `predict quote` before `predict buy` 5. Use a nonzero `--min-shares` value for slippage protection when appropriate Before claiming: 1. Check `profile unclaimed` 2. Prefer `claim batch` when multiple claims are pending 3. Use `--wait` if downstream automation depends on finality Funding safety: - destination tags are mandatory for XRPL relay funding - relay settlement is asynchronous - agents should present funding instructions returned by the CLI rather than improvising transfer details --- ## Embedded Machine-Readable Manifest (JSON) ```json { "skill_name": "axiom-cli-skill", "version": "2.1.0", "last_updated": "2026-03-21", "integration_mode": "axiom-cli-first", "scope": { "mode": "agent-market-operations", "allowed_operations": [ "configure_cli", "create_or_import_wallet", "register_wallet", "get_funding_instructions", "list_markets", "get_market", "quote_prediction", "buy_prediction", "show_profile", "list_positions", "list_unclaimed", "show_rewards", "claim_daily_reward", "claim_weekly_reward", "claim_epoch_reward", "claim_single_market", "claim_batch" ], "forbidden_operations": [ "create_market", "admin_cancel_market", "bootstrap_or_operator_actions", "register_implementation", "upgrade_contracts", "direct_contract_buy_flow", "direct_contract_claim_flow", "manual_market_log_scanning" ] }, "networks": { "xrpl-mainnet": { "chain_id": 1440000, "rpc_url": "https://rpc.xrplevm.org" }, "xrpl-testnet": { "chain_id": 1449000, "rpc_url": "https://rpc.testnet.xrplevm.org" } }, "cli": { "binary": "axiom", "release_urls": { "latest": "https://github.com/Gen3Games/axiom-cli/releases/latest", "all": "https://github.com/Gen3Games/axiom-cli/releases" }, "preferred_output_mode": "json", "config_flags": [ "--api-url", "--rpc-url", "--xrpl-rpc-url", "--profile", "--json" ], "setup_commands": [ "axiom wallet create", "axiom auth register", "axiom funding info" ] }, "command_groups": { "config": [ "axiom config show", "axiom config set --api-url ", "axiom config set --rpc-url ", "axiom config set --xrpl-rpc-url " ], "wallet": [ "axiom wallet create", "axiom wallet import --private-key ", "axiom wallet xrpl-create", "axiom wallet xrpl-import --seed ", "axiom wallet show", "axiom wallet balance" ], "auth": [ "axiom auth register" ], "markets": [ "axiom markets list", "axiom markets list --status open", "axiom markets list --status resolved", "axiom markets list --spot-prices", "axiom markets get " ], "predict": [ "axiom predict quote --label