# Axiom Protocol — Agent Skill (Hosted CLOB CLI)

This skill tells AI agents how to interact with Axiom hosted CLOB prediction markets through the Axiom CLI.

## Primary Rule

Agents should prefer the Axiom CLI for supported hosted CLOB market operations.

Direct contract interaction is not a complete fallback for CLOB trading because active books, orders, fills, and cancellations live behind Axiom's hosted CLOB APIs. XRPL EVM transactions are still used for approvals, CTF split/merge operations, order settlement, and redemption claims.

The preferred workflow is to use the CLI for:

- market discovery
- market metadata and outcome labels
- hosted book depth reads
- wallet approval and balance checks
- signed CLOB order placement
- order cancellation
- order and fill inspection
- complete-set split and merge operations
- CLOB-aware redemption claims
- rewards inspection and reward claims
- funding instructions
- profile inspection

If an agent uses direct chain reads, it should explain that this path cannot reconstruct hosted order book state and may have reduced visibility into market metadata, historical fills, 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 perform read-only explorer or RPC investigation when feasible, while noting the reduced data coverage.

---

## Scope (Hard Rules)

The agent may perform supported Axiom user operations. The CLI is preferred and should be treated as the stable integration surface:

1. Configure the CLI
2. Create or import wallets
3. Register a wallet with Axiom
4. Discover hosted CLOB markets
5. Read market metadata and outcome labels
6. Inspect CLOB books, orders, and fills
7. Prepare wallet approvals for hosted CLOB trading
8. Place signed limit, market, IOC, or FOK orders
9. Cancel the active wallet's own resting orders
10. Split collateral into complete YES/NO sets
11. Merge matching complete sets back into collateral
12. Inspect profile stats, positions, and unclaimed winnings
13. Inspect rewards progress and claim daily, weekly, or epoch rewards
14. Claim a single market or batch claim all unclaimed winnings
15. Show funding instructions for XRPL relay or direct XRPL EVM funding

The agent must not perform privileged or operator-only actions, including:

- market creation
- market resolution
- logical CLOB registration or update
- admin cancellation
- bootstrap or operator flows
- contract upgrades
- implementation registration
- cancelling orders for other wallets
- bypassing the hosted CLOB APIs for order submission

If asked to perform restricted actions, the agent must refuse and explain that those flows are not supported by this public agent skill.

---

## 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`
- App CLI API: `https://axiomprotocol.io/api/cli`
- Console CLI API: `https://console.axiomprotocol.io/api/cli`
- Hosted CLOB projection API: `https://clob.axiomprotocol.io`
- Hosted CLOB eventstore API: `https://clob.axiomprotocol.io/api`

The CLI expects three categories of connectivity:

1. Backend API reads for market discovery, profile data, destination tags, and unclaimed winnings
2. Hosted CLOB projection reads for books, active orders, and fills
3. 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 hosted CLOB markets, place signed orders, inspect profiles, positions, books, orders, and fills, 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 https://axiomprotocol.io/api/cli
./axiom config set --console-api-url https://console.axiomprotocol.io/api/cli
./axiom config set --rpc-url https://rpc.xrplevm.org
./axiom config set --xrpl-rpc-url https://s1.ripple.com:51234
```

Hosted CLOB endpoints are command-scoped and may also be passed as flags:

```text
axiom clob book depth --market <market-id-or-address> --label "Yes" \
  --projection-url https://clob.axiomprotocol.io

axiom clob order place <market-id-or-address> --label "Yes" --side buy --type limit --price 52.5 --quantity 10 \
  --projection-url https://clob.axiomprotocol.io \
  --eventstore-url https://clob.axiomprotocol.io/api
```

For automation and scripting, prefer JSON output:

```text
axiom --json <command>
```

For headless environments without an OS keychain, use the encrypted file-backed secret store:

```text
AXIOM_CLI_SECRET_STORE=file
AXIOM_CLI_SECRET_PASSPHRASE=<strong passphrase>
```

---

## Hosted CLOB Model

Axiom CLOB markets are grouped logical markets backed by one or more binary `AxiomCTFMarket` bindings.

Core concepts:

- A CLOB is a central limit order book where users place signed orders at explicit prices and quantities.
- Books are hosted by Axiom APIs; order settlement and token movements occur on XRPL EVM.
- Prices are displayed as percentages, for example `52.5` means 52.5% or 5250 bps.
- Quantities are whole-number shares.
- A `yes_no` market has one binary binding with displayed `Yes` and `No` sides.
- A `multiple_choice` market has one binary binding per displayed outcome.
- Hosted book identity is side-aware: `{marketId}-{outcomeIndex}-yes|no`.

Token-side guidance:

- Use outcome labels from `markets get`; do not hardcode `Yes` or `No` unless the CLI response confirms them.
- For single-binding `yes_no` markets, selecting displayed `No` can infer the hosted `no` book.
- For multi-binding markets, `--displayed-side no` or `--token-side no` selects the complementary book for the exact logical outcome.
- For CLOB reads, `clob book depth`, `clob orders list`, `clob fills list`, and `clob order cancel` use `--token-side`.
- For CLOB writes, `clob order place` uses `--displayed-side`.

---

## 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 <hex>
```

Optional XRPL wallet support for relay funding:

```text
axiom wallet xrpl-create
axiom wallet xrpl-import --seed <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 <evm-address> --amount <xrp>
```

### 4. Discover hosted CLOB 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 <market-id-or-address>
```

Important guidance:

- prefer market slugs or IDs when available
- use `markets get` to retrieve outcome labels and determine whether the market is a hosted CLOB market
- do not hardcode labels like `Yes` and `No` unless the CLI response confirms them

If the CLI is unavailable, agents may fall back to read-only explorer or contract discovery, but should note that this can miss hosted book state and backend-only metadata.

### 5. Inspect the order book before trading

Read market details, wallet readiness, and current book depth before placing orders:

```text
axiom markets get <market-id-or-address>
axiom clob wallet status <market-id-or-address>
axiom clob book depth --market <market-id-or-address> --label "Yes"
axiom clob book depth --market <market-id-or-address> --label "Yes" --token-side no
```

The book depth command returns:

- hosted `clob_id`
- selected market and outcome
- selected token side
- best bid and ask levels when available
- aggregate depth rows with price, quantity, and order count

Practical guidance:

1. Use book depth to understand available liquidity and spread.
2. Use `--token-side` only after identifying the exact intended hosted book.
3. For marketable orders, check the opposite side of the book first.
4. Do not infer fair value from legacy pool formulas; CLOB prices come from resting orders and fills.

### 6. Prepare wallet approvals

Check readiness:

```text
axiom clob wallet status <market-id-or-address>
```

Approve collateral and outcome-token spending for the hosted exchange:

```text
axiom clob wallet approve <market-id-or-address> --wait
```

The CLI may also auto-approve missing prerequisites during live order placement, but agents should prefer explicit approval checks before trading.

### 7. Place hosted CLOB orders

Use `--dry-run` before live submission for nontrivial orders:

```text
axiom clob order place <market-id-or-address> --label "Yes" --side buy --type limit --price 52.5 --quantity 10 --dry-run
```

Place a live limit order:

```text
axiom clob order place <market-id-or-address> --label "Yes" --side buy --type limit --price 52.5 --quantity 10
```

Place a market order:

```text
axiom clob order place <market-id-or-address> --label "Yes" --side sell --type market --quantity 5
```

Place an IOC order:

```text
axiom clob order place <market-id-or-address> --label "Yes" --side buy --type ioc --price 51 --quantity 20 --dry-run
```

Order rules:

- `--side` is `buy` or `sell`.
- `--type` is `limit`, `market`, `ioc`, or `fok`.
- `--price` is required for non-market orders and is expressed in displayed percent units.
- `--quantity` is whole-number shares.
- `--expiry` accepts presets such as `1h`, `24h`, `7d`, or `never`.
- Limit orders must be settleable on-chain at the selected price and quantity.
- The live command signs the order locally and submits it through the hosted CLOB eventstore.

### 8. Inspect and cancel orders

List orders for one book:

```text
axiom clob orders list --market <market-id-or-address> --label "Yes" --active-only
```

List orders for the active wallet:

```text
axiom clob orders list --mine --active-only
```

Fetch one order:

```text
axiom clob order get --order-id <order-id>
```

Cancel an order owned by the active wallet:

```text
axiom clob order cancel --order-id <order-id> --market <market-id-or-address> --label "Yes"
```

Safety guidance:

1. Confirm the order belongs to the active wallet before cancellation.
2. Include the market and label so the CLI can build the correct hosted cancellation payload.
3. Do not attempt to cancel another wallet's orders.

### 9. Inspect fills

List recent fills for one book:

```text
axiom clob fills list --market <market-id-or-address> --label "Yes"
```

List fills involving the active wallet:

```text
axiom clob fills list --mine
```

Fetch one fill:

```text
axiom clob fills get --fill-id <fill-id>
```

Use fills, not submitted orders, as the source of truth for executed trading activity.

### 10. Manage complete sets

CLOB markets use conditional tokens. Splitting collateral creates a complete YES/NO set for one binding; merging matching YES and NO tokens returns collateral.

Check split and merge readiness:

```text
axiom clob split-status <market-id-or-address> --label "Yes"
```

Split collateral into complete sets:

```text
axiom clob split <market-id-or-address> --label "Yes" --amount 5 --wait
```

Merge the maximum matching YES/NO amount back to collateral:

```text
axiom clob merge <market-id-or-address> --label "Yes" --max --wait
```

Complete-set guidance:

1. Splitting is mainly useful for users who need outcome-token inventory for asks or market making.
2. Buying can usually be done with collateral after wallet approval.
3. Merging requires matching YES and NO balances for the same binding.
4. Use `split-status` before split or merge actions.

### 11. Inspect profile state

```text
axiom profile show
axiom profile update --display-name <name>
axiom profile update --avatar-url <https-url>
axiom profile positions
axiom profile unclaimed
```

These commands are the preferred way to inspect activity and pending winnings.

### 12. 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.

### 13. Claim winnings through the CLI

Claim a single market:

```text
axiom claim market <market-id-or-address>
```

Claim all currently unclaimed winnings returned by the backend:

```text
axiom claim batch
axiom claim batch --wait
```

On grouped CLOB markets, `axiom claim market` inspects all bound binary contracts under the logical market and only redeems contracts that actually hold redeemable YES or NO balances for the active wallet.

---

## Market-Maker Convenience Commands

The `axiom mm` surface is an optional operator convenience layer above lower-level `axiom clob` commands. Use it only when the user is explicitly acting as a liquidity provider.

Common market-maker workflow:

```text
axiom mm market list --search xrp
axiom mm market use <market-id-or-address>
axiom mm market show
axiom mm status --label "Yes" --displayed-side yes
axiom mm book --label "Yes" --displayed-side yes
axiom mm mint --label "Yes" --amount 3.0 --wait
axiom mm quote --label "Yes" --displayed-side yes --bid-price 45 --ask-price 55 --quantity 3 --dry-run
axiom mm quote --label "Yes" --displayed-side yes --bid-price 45 --ask-price 55 --quantity 3
axiom mm cancel-all --label "Yes" --displayed-side yes
```

Market-maker rules:

- `mm quote` posts one two-sided quote to one exact hosted book.
- `mm cancel-all` should be scoped with `--label` and `--displayed-side` when possible.
- `mm mint` splits collateral into complete sets for one binding.
- `mm` does not run an autonomous bot; it is a manual operator layer.

---

## Automation Rules

For agent automation, prefer:

- `axiom --json markets list --status open`
- `axiom --json markets get <market-id-or-address>`
- `axiom --json clob wallet status <market-id-or-address>`
- `axiom --json clob book depth --market <market-id-or-address> --label <label>`
- `axiom --json clob order place <market-id-or-address> --label <label> --side buy --type limit --price <price> --quantity <shares> --dry-run`
- `axiom --json clob orders list --mine --active-only`
- `axiom --json clob fills list --mine`
- `axiom --json profile show`
- `axiom --json profile unclaimed`
- `axiom --json rewards show`

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. Inspect `clob book depth` before placing marketable orders.
4. Run `clob order place --dry-run` before live order submission for nontrivial trades.
5. Use `--wait` when approval, split, merge, claim, or funding workflows require confirmed settlement before the next step.
6. Surface CLI errors directly, and if falling back to contract-level logic, explain that the result does not include hosted CLOB book state.

---

## Safety Rules

Before trading:

1. Confirm the CLI is pointed at the intended API, CLOB, and RPC URLs.
2. Confirm the market exists through `markets get`.
3. Confirm the requested outcome label or index is valid.
4. Confirm the intended hosted book and token side.
5. Inspect `clob book depth` for liquidity and spread.
6. Check `clob wallet status` for balances and approvals.
7. Prefer `clob order place --dry-run` before live submission.
8. Use explicit prices and whole-number quantities.

Before cancelling:

1. Check `clob orders list --mine --active-only`.
2. Confirm the order ID belongs to the active wallet.
3. Pass the market and label when cancelling.

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-clob-skill",
  "version": "3.0.0",
  "last_updated": "2026-05-26",
  "integration_mode": "axiom-cli-hosted-clob-first",
  "scope": {
    "mode": "agent-clob-market-operations",
    "allowed_operations": [
      "configure_cli",
      "create_or_import_wallet",
      "register_wallet",
      "get_funding_instructions",
      "list_markets",
      "get_market",
      "inspect_clob_book_depth",
      "inspect_clob_wallet_status",
      "approve_clob_wallet",
      "place_clob_order",
      "dry_run_clob_order",
      "cancel_own_clob_order",
      "list_clob_orders",
      "list_clob_fills",
      "get_clob_order",
      "get_clob_fill",
      "split_complete_sets",
      "merge_complete_sets",
      "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",
      "resolve_market",
      "register_logical_clob_market",
      "update_logical_clob_market",
      "admin_cancel_market",
      "bootstrap_or_operator_actions",
      "register_implementation",
      "upgrade_contracts",
      "cancel_other_wallet_orders",
      "bypass_hosted_clob_order_submission",
      "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"
    }
  },
  "clob_endpoints": {
    "app_api_url": "https://axiomprotocol.io/api/cli",
    "console_api_url": "https://console.axiomprotocol.io/api/cli",
    "projection_url": "https://clob.axiomprotocol.io",
    "eventstore_url": "https://clob.axiomprotocol.io/api",
    "default_chain_id": 1440000
  },
  "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",
      "--console-api-url",
      "--rpc-url",
      "--xrpl-rpc-url",
      "--projection-url",
      "--eventstore-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 <url>",
      "axiom config set --console-api-url <url>",
      "axiom config set --rpc-url <url>",
      "axiom config set --xrpl-rpc-url <url>"
    ],
    "wallet": [
      "axiom wallet create",
      "axiom wallet import --private-key <hex>",
      "axiom wallet xrpl-create",
      "axiom wallet xrpl-import --seed <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 <market-id-or-address>"
    ],
    "clob_wallet": [
      "axiom clob wallet status <market-id-or-address>",
      "axiom clob wallet approve <market-id-or-address> --wait"
    ],
    "clob_books": [
      "axiom clob book depth --market <market-id-or-address> --label <label>",
      "axiom clob book depth --market <market-id-or-address> --label <label> --token-side no"
    ],
    "clob_orders": [
      "axiom clob order place <market-id-or-address> --label <label> --side buy --type limit --price <price> --quantity <shares> --dry-run",
      "axiom clob order place <market-id-or-address> --label <label> --side buy --type limit --price <price> --quantity <shares>",
      "axiom clob order place <market-id-or-address> --label <label> --side sell --type market --quantity <shares>",
      "axiom clob orders list --market <market-id-or-address> --label <label> --active-only",
      "axiom clob orders list --mine --active-only",
      "axiom clob order get --order-id <order-id>",
      "axiom clob order cancel --order-id <order-id> --market <market-id-or-address> --label <label>"
    ],
    "clob_fills": [
      "axiom clob fills list --market <market-id-or-address> --label <label>",
      "axiom clob fills list --mine",
      "axiom clob fills get --fill-id <fill-id>"
    ],
    "clob_inventory": [
      "axiom clob split-status <market-id-or-address> --label <label>",
      "axiom clob split <market-id-or-address> --label <label> --amount <xrp> --wait",
      "axiom clob merge <market-id-or-address> --label <label> --max --wait"
    ],
    "mm_optional": [
      "axiom mm market list --search <term>",
      "axiom mm market use <market-id-or-address>",
      "axiom mm status --label <label> --displayed-side yes",
      "axiom mm quote --label <label> --displayed-side yes --bid-price <price> --ask-price <price> --quantity <shares> --dry-run",
      "axiom mm quote --label <label> --displayed-side yes --bid-price <price> --ask-price <price> --quantity <shares>",
      "axiom mm cancel-all --label <label> --displayed-side yes"
    ],
    "profile": [
      "axiom profile show [wallet-address]",
      "axiom profile update --display-name <name>",
      "axiom profile update --avatar-url <https-url>",
      "axiom profile positions [wallet-address]",
      "axiom profile unclaimed [wallet-address]"
    ],
    "rewards": [
      "axiom rewards show [wallet-address]",
      "axiom rewards claim daily",
      "axiom rewards claim weekly [ticket-id]",
      "axiom rewards claim epoch [epoch-id]"
    ],
    "claim": [
      "axiom claim market <market-id-or-address>",
      "axiom claim batch",
      "axiom claim batch --wait"
    ],
    "funding": [
      "axiom funding info [wallet-address]",
      "axiom funding bridge",
      "axiom funding bridge --amount <xrp>",
      "axiom funding direct --to <evm-address> --amount <xrp>"
    ]
  },
  "agent_policy": {
    "prefer_cli_over_contracts": true,
    "require_book_depth_before_marketable_order": true,
    "prefer_order_dry_run_before_live_submission": true,
    "prefer_json_for_automation": true,
    "use_cli_errors_as_source_of_truth": true,
    "fallback_to_direct_contract_calls": "read-only-or-settlement-only",
    "fallback_warning": "Direct contract interaction cannot reconstruct hosted CLOB books, active orders, fills, or cancellations because those surfaces are served by Axiom hosted CLOB APIs."
  },
  "secret_storage": {
    "preferred": "os-keychain",
    "fallback": "encrypted-local-file",
    "env": [
      "AXIOM_CLI_SECRET_STORE=file",
      "AXIOM_CLI_SECRET_PASSPHRASE=<strong passphrase>"
    ]
  }
}
```

---

## Practical Notes

- Use the CLI as the stable hosted CLOB integration surface.
- Treat CLI responses as the source of truth for market labels, hosted book selection, profile stats, unclaimed winnings, and batch-claim candidates.
- Treat `markets list` as open-by-default market discovery, with `--status resolved` as the supported historical mode.
- Treat fills, not submitted orders, as the source of truth for executed trades.
- Direct contract interaction is allowed only for narrow chain reads or settlement fallbacks; it cannot replace hosted CLOB book, order, and fill APIs.
- If you need advanced, privileged, market-creation, resolution, or upgrade behavior, that is outside this skill's scope.