Mantle

Skills

skills/ contains one directory per Mantle-focused agent skill. Each skill combines a primary workflow in SKILL.md with local references or assets so the runtime can ground answers in repository data instead of relying only on model memory.

Directory Convention

• skills/<skill-name>/SKILL.md: trigger conditions, workflow, guardrails, and output format
• skills/<skill-name>/agents/openai.yaml: runtime-facing metadata
• skills/<skill-name>/references/: playbooks, policies, templates, and supporting notes
• skills/<skill-name>/assets/: machine-readable local data used by the skill

Skill Catalog

Onboarding and Reference

Registry and Safety Gates

Analytics and Diagnostics

DeFi Planning

Smart Contract Lifecycle

How to Pick a Skill

• Start with the narrowest skill that matches the task.
• Use mantle-network-primer when Mantle-specific assumptions need to be checked before execution work.
• Use mantle-defi-operator only when the request genuinely spans discovery, address verification, risk evidence, and execution planning.
• Split contract work between mantle-smart-contract-developer and mantle-smart-contract-deployer rather than treating deployment as part of design.

Address Registry Playbook

Use this file with assets/registry.json to keep address lookups deterministic and auditable.

Resolution Policy

• CLI commands for address resolution (do NOT use MCP server):
• Use mantle-cli token resolve <symbol> --json for token symbols/names.
• Use mantle-cli registry resolve <identifier> --json for contract key/alias/label lookups.
• Use mantle-cli registry validate <address> --json before returning any final address.
• Prefer machine-readable sources over free text.
• Treat missing or stale provenance as a safety failure.
• Fail closed: no verified entry means no address output.

Registry Fields

Each contracts[] entry should include:

• key: stable lookup key (WETH, OFFICIAL_BRIDGE, and so on)
• label: human-readable name
• environment: mainnet or testnet (runtime network=sepolia maps to testnet)
• category: system, token, bridge, or defi
• address: EIP-55 checksum address
• status: active, deprecated, paused, or unknown
• is_official: boolean
• source.url: canonical source page
• source.retrieved_at: ISO-8601 timestamp
• aliases: optional alternate names/symbols
• protocol_id: optional normalized protocol slug for DeFi entries
• contract_role: optional normalized role such as router, quoter, position_manager, pool, or pool_addresses_provider
• supports: optional list of supported operations such as swap, add_liquidity, remove_liquidity, supply, or withdraw

Lookup Strategy

1. If CLI is available, resolve through mantle-cli token resolve/mantle-cli registry resolve first. 2. Local fallback: exact match on key. 3. For defi lookups, if the request includes a protocol and role, filter by exact protocol_id + contract_role. 4. Local fallback: exact match on alias/symbol. 5. Local fallback: case-insensitive match on label. 6. If multiple active DeFi entries remain for the same protocol, stop and request role disambiguation.

Freshness Guidance

• Prefer entries verified within the last 30 days.
• If older than 30 days, set confidence to medium.
• If no timestamp exists, set confidence to low and require manual confirmation.
• If status is not active, do not treat as executable target.

Update Procedure

1. Gather source from official Mantle docs, official protocol docs, an official app config bundle, or a verified explorer contract page linked from an official source. 2. Update or add the entry in assets/registry.json. 3. Set source.retrieved_at and top-level updated_at to current UTC timestamp. 4. Preserve old entries by marking them deprecated instead of deleting immediately. 5. Re-run validation checks before using updated entries for execution tasks.

Suggested Validation Checks

• Address format and checksum.
• No placeholder/template values (for example REPLACE_WITH_EIP55_CHECKSUM_ADDRESS).
• Duplicated keys within the same environment.
• Duplicated active addresses with conflicting labels.
• Missing source URL or retrieved timestamp.

Indexer Selection and Quality

Use this guide to choose index sources and communicate confidence.

Tool mapping and endpoint availability

• GraphQL path: use mantle-cli indexer subgraph --endpoint <url> --query <graphql> --json.
• SQL path: use mantle-cli indexer sql --endpoint <url> --query <sql> --json.
• Endpoints are runtime inputs; do not fabricate URLs when missing.
• For E2E endpoint-configured scenarios, E2E_SUBGRAPH_ENDPOINT / E2E_SQL_ENDPOINT may be unset and those scenarios should be skipped.

Source choice

• Choose GraphQL when:
• A maintained subgraph exists.
• You need flexible entity filtering and nested fields.
• Choose SQL when:
• A warehouse/indexer table exists for the target protocol.
• You need heavy aggregations or window functions.

Required metadata in every answer

• source_type (graphql or sql)
• Endpoint or dataset name
• Time range in absolute UTC timestamps
• Query execution time (queried_at_utc)
• Known lag status (if available)

Data quality checks

1. Confirm chain scope is Mantle. 2. Confirm timestamp units (seconds vs milliseconds). 3. Confirm decimal normalization assumptions. 4. Confirm pagination did not truncate data (hasNextPage=true warning requires follow-up pages). 5. Confirm SQL result truncation (truncated=true) did not hide required rows. 6. Confirm sorting/order key is deterministic.

Lag and completeness policy

• If lag is unknown, say lag status unknown.
• If lag is known and non-trivial, include impact statement.
• If query fails partway, report partial result with clear boundary.
• If tool warnings are present, copy them into output and explain impact.

Common failure modes

• Query returns zero rows because wrong network or wrong entity ID.
• Endpoint missing and agent guesses an URL instead of requesting one.
• Aggregation mismatch due to unnormalized token decimals.
• Double-counting due to overlapping pagination windows.
• Misleading totals due to mixed time granularities.

Query Templates

Use these templates as starting points. Replace placeholders explicitly.

Tool argument mapping (CLI)

• GraphQL template -> mantle-cli indexer subgraph --json with:
• --endpoint <url> (required)
• --query <graphql> (required)
• --variables <json> (optional)
• SQL template -> mantle-cli indexer sql --json with:
• --endpoint <url> (required)
• --query <sql> (required, read-only SQL only)
• --params <json> (optional)
• In E2E endpoint-configured scenarios, endpoint placeholders come from E2E_SUBGRAPH_ENDPOINT / E2E_SQL_ENDPOINT; if unset, those scenarios are skipped.

GraphQL: wallet swap history (template)

query WalletSwaps(
  $wallet: String!,
  $startTs: Int!,
  $endTs: Int!,
  $first: Int!,
  $skip: Int!
) {
  swaps(
    where: {
      trader: $wallet
      timestamp_gte: $startTs
      timestamp_lte: $endTs
    }
    orderBy: timestamp
    orderDirection: asc
    first: $first
    skip: $skip
  ) {
    id
    txHash
    timestamp
    tokenIn
    tokenOut
    amountIn
    amountOut
  }
}

GraphQL: pool daily volume (template)

query PoolDailyVolume(
  $poolId: String!,
  $startDay: Int!,
  $endDay: Int!,
  $first: Int!,
  $skip: Int!
) {
  poolDayDatas(
    where: {
      pool: $poolId
      date_gte: $startDay
      date_lte: $endDay
    }
    orderBy: date
    orderDirection: asc
    first: $first
    skip: $skip
  ) {
    date
    volumeUSD
    txCount
  }
}

SQL: wallet activity rollup (template)

SELECT
  DATE_TRUNC('day', block_time) AS day_utc,
  COUNT(*) AS tx_count,
  SUM(amount_usd) AS volume_usd
FROM swaps
WHERE chain_id = 5000
  AND LOWER(wallet_address) = LOWER(:wallet)
  AND block_time >= :start_utc
  AND block_time < :end_utc
GROUP BY 1
ORDER BY 1 ASC;

SQL: top pools by 24h volume (template)

SELECT
  pool_address,
  SUM(amount_usd) AS volume_24h_usd,
  COUNT(*) AS swap_count
FROM swaps
WHERE chain_id = 5000
  AND block_time >= :window_start_utc
  AND block_time < :window_end_utc
GROUP BY pool_address
ORDER BY volume_24h_usd DESC
LIMIT :limit_n;

Template usage rules

• Always declare timestamp timezone as UTC in parameters and output.
• Use deterministic ordering plus pagination for large result sets.
• Keep SQL read-only; avoid INSERT/UPDATE/DELETE/DDL statements.
• State whether amounts are raw token units or USD-normalized.
• Include replaced parameter values in report appendix.
• Carry forward tool warnings (hasNextPage=true, truncated) in the final report.

DeFi Pre-Execution Guardrails

Apply these controls before any potential state-changing DeFi action.

Tool discovery via Capability Catalog

• Read mantle://registry/capabilities to discover available tools before constructing any plan.
• Use category to filter: query for reads, analyze for insights, execute for transaction building.
• Use auth to check wallet requirements: required tools need a wallet address, none tools don't.
• Use workflow_before to understand call ordering (e.g., getSwapQuote before buildSwap).
• For simple read-only tasks (query/analyze), the Capability Catalog is sufficient — no skill loading needed.
• For execution planning, continue with the guardrails below.

Capability boundary (CLI-only)

• All on-chain operations use mantle-cli commands with --json. Do NOT enable or connect to the MCP server.
• The CLI is read-focused for queries and builds unsigned transactions for writes — it does not sign, broadcast, deploy, or execute transactions.
• This skill must stop at analysis + plan generation.
• Never fabricate tx hashes, receipts, or settlement outcomes.

Coordination boundary

• Use this skill to assemble a final plan, not to replace specialized address, risk, or portfolio skills.
• Route address trust to mantle-address-registry-navigator.
• Route pass/warn/block verdicts to $mantle-risk-evaluator.
• Route allowance and balance evidence to $mantle-portfolio-analyst when approval scope or wallet coverage matters.

Address trust

• Resolve execution-ready token/router/pool/position-manager addresses from the shared mantle-address-registry-navigator registry.
• Mark the plan as blocked for unverified or malformed addresses.
• Mention the selected registry key in the final handoff.
• Discovery-only protocols may be mentioned for comparison, but they are not execution targets until their contracts are verified.
• Live metrics may influence ranking, but they never establish address trust.

Intent completeness

• Ensure operation type, token amounts, recipient, slippage cap, and deadline are present.
• Mark the plan as blocked if any mandatory field is missing.

Risk coupling

• Require latest preflight verdict from $mantle-risk-evaluator when available.
• For warn/high-risk outcomes, require explicit user confirmation.
• For block outcomes, do not produce an execution-ready plan.

Allowance controls

• Prefer minimal required approval over unlimited approval.
• Use $mantle-portfolio-analyst when allowance scope, spender exposure, or balance coverage needs read-only evidence.
• If unlimited approval is requested, require explicit user acknowledgement.
• Include an explicit allowance re-check in the external execution checklist.

Execution handoff integrity

• Use deterministic route and calldata inputs from selected quote/liquidity context.
• Record required call sequence and parameter values for the external executor.
• Define post-execution reconciliation checks (balances/allowances/slippage) to run after user-confirmed execution.

Lending SOP

Use this standard flow for Aave V3 lending operations (supply, borrow, repay, withdraw) on Mantle.

CRITICAL: Use CLI for Transaction Building

ALWAYS use `mantle-cli` to build unsigned transactions. Do NOT manually construct calldata, extract addresses from text, or build approve calls yourself. The CLI handles address resolution, ABI encoding, and whitelist validation correctly.

# All commands support --json for structured output
mantle-cli aave supply   --asset USDC --amount 1.0 --on-behalf-of 0x... --json
mantle-cli aave borrow   --asset USDC --amount 0.5 --on-behalf-of 0x... --json
mantle-cli aave repay    --asset USDC --amount 0.5 --on-behalf-of 0x... --json
mantle-cli aave repay    --asset USDC --amount max --on-behalf-of 0x... --json
mantle-cli aave withdraw --asset USDC --amount 1.0 --to 0x... --json
mantle-cli aave withdraw --asset USDC --amount max --to 0x... --json
mantle-cli aave markets  --json  # check APY/TVL before deciding

For approvals (required before supply/repay):

mantle-cli swap approve --token USDC --spender 0x458F293454fE0d67EC0655f3672301301DD51422 --amount max --json

The CLI outputs unsigned_tx with to, data, value, chainId — no `from` field. Pass this directly to the signer without modification.

Step 1: Check lending markets

mantle-cli aave markets --json

• Review supply APY, borrow APY, TVL, LTV, and liquidation threshold.
• Confirm the target asset is a supported Aave V3 reserve.
• Supported assets: WETH, WMNT, USDT0, USDC, USDe, sUSDe, FBTC, syrupUSDT, wrsETH, GHO.

Step 2: Normalize input

• Asset symbol or address
• Amount (decimal, or max for repay/withdraw)
• Wallet address (on_behalf_of for supply/borrow/repay, to for withdraw)

Step 3: Check balance and allowance

mantle-cli account balance <wallet> --tokens USDC,USDT0 --json

• Verify the wallet has sufficient token balance for supply/repay.
• The Aave Pool address is 0x458F293454fE0d67EC0655f3672301301DD51422.

Step 4: Approve if needed

If allowance is insufficient for supply or repay:

mantle-cli swap approve --token USDC \
  --spender 0x458F293454fE0d67EC0655f3672301301DD51422 \
  --amount <exact_or_max> --owner <wallet> --json

• The CLI validates the spender against the whitelist.
• Use --owner to check existing allowance and skip if already sufficient.
• Sign and broadcast the approve unsigned_tx before proceeding to supply/repay.

Step 5: Build the lending transaction

Use the appropriate CLI command:

Always use --json to get structured output for the signer.

Step 6: Sign and broadcast

• Pass the unsigned_tx object directly to the external signer.
• Do NOT add a `from` field — the signer determines from from the signing key.
• Do NOT modify `to`, `data`, `value`, or `chainId` fields.

Step 7: Post-execution verification

• Re-read token balance and aToken balance to confirm the operation.
• For supply: verify aToken balance increased.
• For borrow: verify token balance increased and debt token appeared.
• For repay: verify debt token balance decreased.
• For withdraw: verify aToken balance decreased and token balance increased.
• Check health factor after borrow/withdraw to ensure it remains above 1.0.

Common pitfalls

• Missing approve: supply and repay require prior ERC-20 approval for the Aave Pool.
• `from` field in unsigned_tx: NEVER add from — this breaks Privy and some signers.
• Stale allowance: use --owner flag in approve to auto-skip if sufficient.
• Health factor: borrow and withdraw reduce health factor — check before proceeding.
• `max` semantics: repay max repays full debt; withdraw max withdraws full balance.

Liquidity SOP

Use this flow for LP operations on Mantle (V3: Agni/Fluxion, LB: Merchant Moe).

CRITICAL: Use CLI for All LP Operations

ALWAYS use `mantle-cli` to build LP transactions and query positions. The CLI handles pool resolution, tick range calculation, ABI encoding, and position enumeration.

# Read operations (no signing needed)
mantle-cli lp find-pools --token-a USDC --token-b USDe --json  # Discover ALL pools across ALL DEXes
mantle-cli lp positions --owner 0x... --json          # List all V3 positions
mantle-cli lp pool-state --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --json
mantle-cli lp suggest-ticks --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --json
mantle-cli lp analyze --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --investment-usd 1000 --json
mantle-cli defi lb-state --token-a USDC --token-b USDT0 --bin-step 1 --json

# Write operations (returns unsigned_tx)
mantle-cli lp add --provider agni --token-a USDC --token-b WMNT --amount-a 10 --amount-b 15 --recipient 0x... --json
mantle-cli lp add --provider agni --token-a USDC --token-b WMNT --amount-usd 1000 --recipient 0x... --json  # USD mode
mantle-cli lp remove --provider agni --token-id 12345 --liquidity 1000000 --recipient 0x... --json
mantle-cli lp remove --provider agni --token-id 12345 --percentage 50 --recipient 0x... --json  # Remove 50%
mantle-cli lp collect-fees --provider agni --token-id 12345 --recipient 0x... --json

Step 1: Pool Discovery — ALWAYS Start Here

Before any LP operation, use `find-pools` to discover ALL available pools across ALL DEXes. This queries factory contracts on-chain — the authoritative source. Do NOT rely on DexScreener, subgraphs, or hardcoded pair lists.

mantle-cli lp find-pools --token-a USDC --token-b USDe --json

This returns every pool with its DEX provider, fee tier/bin step, pool address, and liquidity status. Example output for USDC/USDe:

• Agni fee=100 (0.01%) — $1.7M liquidity
• Merchant Moe bin=1 — active

Use the results to pick the best pool, then proceed with pool analysis.

Step 2: Pool Analysis — ALWAYS Before Adding Liquidity

After picking a pool, run `lp analyze` to understand APR, risk, and optimal range.

mantle-cli lp analyze --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --investment-usd 5000 --json

The analysis returns:

• Fee APR based on 24h volume / TVL (base and concentrated across 10 range brackets)
• Risk assessment: TVL risk, volatility risk, concentration risk
• Investment projections: daily/weekly/monthly fee income for your investment amount
• Recommended range: auto-selected based on recent volatility (±3× daily movement)
• Multi-range comparison: ±1% through ±50% with APR, concentration factor, and rebalance risk

Use this data to make an informed range decision. Do NOT skip analysis and guess a tick range.

Step 3: Pool State & Tick Suggestions

After analysis, get exact tick bounds:

V3 Pools (Agni/Fluxion)

# 1. Check pool state — get current tick, price, liquidity
mantle-cli lp pool-state --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --json

# 2. Get tick range suggestions (pre-calculated wide/moderate/tight)
mantle-cli lp suggest-ticks --token-a USDC --token-b WMNT --fee-tier 10000 --provider agni --json

# 3. List existing positions
mantle-cli lp positions --owner 0x... --json

Merchant Moe LB Pairs

# Check LB pair state — get active bin, nearby bin reserves
mantle-cli defi lb-state --token-a USDC --token-b USDT0 --bin-step 1 --json

Step 4: Tick/Bin Range Selection

V3 (Agni/Fluxion)

Use data from lp analyze (recommended range) and lp suggest-ticks to pick a range:

• tight (±1-3%): stablecoins or low-volatility pairs — highest APR but frequent rebalancing
• moderate (±5-10%): balanced risk/reward for most pairs
• wide (±15-50%): volatile pairs, less rebalancing needed

Do NOT manually calculate ticks — use the CLI tools.

Merchant Moe LB

Use defi lb-state to get the active_id, then:

• For stablecoins: use delta_ids: [-2,-1,0,1,2] centered on active bin
• For volatile: use wider range delta_ids: [-5,-4,...,4,5]
• Distribution: uniform [1e18, 1e18, ...] for even, or custom weights

Step 5: Add Liquidity

Amount modes

Token amounts (explicit control):

mantle-cli lp add --provider agni \
  --token-a USDC --token-b WMNT \
  --amount-a 10 --amount-b 15 \
  --tick-lower <from_analyze> --tick-upper <from_analyze> \
  --fee-tier 10000 --recipient 0x... --json

USD amount (automatic sizing — recommended for user-facing flows):

mantle-cli lp add --provider agni \
  --token-a USDC --token-b WMNT \
  --amount-usd 1000 \
  --tick-lower <from_analyze> --tick-upper <from_analyze> \
  --fee-tier 10000 --recipient 0x... --json

The --amount-usd mode:

• Fetches live token prices from DexScreener/DefiLlama
• Reads pool state to compute the correct token ratio for the target tick range (not a naive 50/50 split)
• Reports the computed amounts and prices in the response warnings
• Falls back to 50/50 for full-range positions or if pool read fails

Merchant Moe

mantle-cli lp add --provider merchant_moe \
  --token-a USDC --token-b USDT0 \
  --amount-a 100 --amount-b 100 \
  --bin-step 1 --active-id <from_lb_state> \
  --delta-ids '[-2,-1,0,1,2]' \
  --distribution-x '[200000000000000000,200000000000000000,200000000000000000,200000000000000000,200000000000000000]' \
  --distribution-y '[200000000000000000,200000000000000000,200000000000000000,200000000000000000,200000000000000000]' \
  --recipient 0x... --json

Step 6: Fee Collection (V3)

# Check accrued fees first
mantle-cli lp positions --owner 0x... --json
# Look for tokens_owed0 / tokens_owed1 > 0

# Collect fees
mantle-cli lp collect-fees --provider agni --token-id 12345 --recipient 0x... --json

Step 7: Remove Liquidity

V3 — Exact amount

mantle-cli lp remove --provider agni \
  --token-id 12345 --liquidity <amount> \
  --recipient 0x... --json

V3 — Percentage mode (recommended for user-facing flows)

# Remove 50% of position
mantle-cli lp remove --provider agni \
  --token-id 12345 --percentage 50 \
  --recipient 0x... --json

# Remove all
mantle-cli lp remove --provider agni \
  --token-id 12345 --percentage 100 \
  --recipient 0x... --json

The --percentage mode reads the position's current liquidity on-chain and calculates the exact amount to remove. No need to manually query lp positions for the raw liquidity number.

Merchant Moe

mantle-cli lp remove --provider merchant_moe \
  --token-a USDC --token-b USDT0 \
  --bin-step 1 \
  --ids '[8388608,8388609,8388610]' \
  --amounts '[1000000,1000000,1000000]' \
  --recipient 0x... --json

Step 8: Post-operation Verification

• Re-read positions: lp positions --owner 0x... --json
• Check token balances changed as expected
• For V3: verify in_range status if market moved
• For Moe: verify bin balances via defi lb-state

Common Pitfalls

• Skipping pool analysis: ALWAYS run lp analyze before adding liquidity — it shows APR, risk, and recommended range
• Skipping pool discovery: ALWAYS run lp find-pools first — it finds pools DexScreener misses (e.g. Agni fee=0.01% stablecoin pools)
• Full-range V3 LP: extremely capital-inefficient — always use analysis + tick suggestions to pick a range
• Wrong active_id for Moe: always read fresh from defi lb-state, never hardcode
• Missing approve: both tokens must be approved for the router/position manager before adding
• Manual amount calculation: use --amount-usd instead of manually computing token splits from prices
• Manual liquidity lookup for removal: use --percentage instead of manually reading position liquidity
• `from` field: NEVER add to unsigned_tx
• V3 position enumeration: lp positions discovers all positions across both Agni and Fluxion
• Fee harvesting: use lp collect-fees standalone — no need to remove liquidity to collect fees

Protocol Selection Policy

Candidate gating

• Only recommend protocols whose contract addresses resolve from mantle-address-registry-navigator.
• Ignore discovery-only protocols for execution-ready guidance.
• Block recommendations when required contract roles are missing.
• Treat curated defaults as candidate seeds, not proof of execution readiness.
• Carry forward curated retrieved_at / review_after metadata into freshness reporting.

Ranking signals

Swaps

• quote quality
• recent volume
• pool depth
• slippage risk

Liquidity

• TVL
• recent volume
• pool fit
• operational complexity

Lending

• TVL
• utilization
• asset support
• withdrawal liquidity

Fallbacks

• If live metrics are unavailable, fall back to curated default order.
• If only one curated verified candidate fits the action, recommend it first before asking follow-up preferences.
• If the score delta is small, keep the curated default first.
• If the user names another protocol, verify it before comparing it.
• If risk or allowance evidence is missing, downgrade readiness and request supporting skill output before presenting an execution-ready handoff.

Mode-specific output rules

• discovery_only: return high-level venue suggestions, rationale, and discovery sources only.
• discovery_only: do not include router addresses, calldata, approval steps, or execution sequencing.
• compare_only: verified registry keys or contract roles may be cited, but calldata and approval instructions remain out of scope.
• execution_ready: allowed only after verified address trust plus the required risk and portfolio evidence are available or intentionally marked unnecessary.

Discovery messaging

• Mention DefiLlama for broader ecosystem discovery.
• Do not treat DefiLlama as a contract-truth or execution-readiness source.

Swap SOP

Use this standard flow for token swap pre-execution analysis on Mantle.

CRITICAL: Use CLI for Transaction Building

ALWAYS use `mantle-cli` to build unsigned transactions. Do NOT manually construct calldata, extract addresses from text, or build approve calls yourself. The CLI handles address resolution, ABI encoding, pool parameter lookup, multi-hop routing, and whitelist validation correctly.

# Build the swap transaction — works for both direct and multi-hop routes
mantle-cli swap build-swap --provider fluxion --in WMNT --out BSB \
  --amount 0.5 --recipient 0x... --json

# If approval is needed
mantle-cli swap approve --token WMNT --spender <router_address> \
  --amount <exact_or_max> --owner <wallet> --json

# Check available pairs and pool parameters
mantle-cli swap pairs --provider fluxion --json

The CLI outputs unsigned_tx with to, data, value, chainId — no `from` field. Pass this directly to the signer without modification.

Multi-hop Routing (Built-in)

The CLI automatically discovers multi-hop routes when no direct pair exists. You do NOT need to find intermediate pools or build multi-step swaps yourself.

How it works: when --in A --out B has no direct pool, the CLI tries 2-hop paths via bridge tokens (WMNT, USDC, USDT0, USDe, WETH) using the registered pair registry. If a route A → bridge → B exists, it builds a single exactInput (V3) or multi-token-path (Merchant Moe) transaction.

Examples of auto-routed swaps:

# WMNT → BSB  (auto-routes: WMNT → USDT0 → BSB on Fluxion)
mantle-cli swap build-swap --provider fluxion --in WMNT --out BSB --amount 0.5 --recipient 0x... --json

# WMNT → wTSLAx  (auto-routes: WMNT → USDC → wTSLAx on Fluxion)
mantle-cli swap build-swap --provider fluxion --in WMNT --out wTSLAx --amount 0.5 --recipient 0x... --json

# WMNT → ELSA  (auto-routes: WMNT → USDT0 → ELSA on Fluxion)
mantle-cli swap build-swap --provider fluxion --in WMNT --out ELSA --amount 0.5 --recipient 0x... --json

What you MUST NOT do:

• Do NOT manually split a swap into two separate transactions (e.g. WMNT→USDT0 then USDT0→BSB). The CLI handles this as a single atomic multi-hop transaction with better gas efficiency.
• Do NOT search for intermediate pools or bridge tokens yourself. The CLI's route discovery uses the verified pair registry.
• Do NOT use aggregators or external routing services. Only use mantle-cli swap build-swap.

When multi-hop is used, the response will show:

• intent: "swap_multihop" (instead of "swap")
• human_summary shows the full path (e.g. "Swap 0.5 WMNT → BSB via WMNT → USDT0 → BSB on Fluxion")
• warnings include the route details and fee tiers

Step 1: Normalize input

• token in/out symbols or addresses
• exact input amount
• recipient address
• slippage cap (default 0.5%)

Step 2: Select candidate protocol

• Start with curated defaults: Merchant Moe, Agni, Fluxion.
• Use mantle-cli swap pairs --json to check available pairs and pool parameters per DEX.
• Resolve the execution-ready router/quoter from mantle-address-registry-navigator.
• If the user names another venue, verify its contracts before comparing it.
• For xStocks RWA tokens (wTSLAx, wAAPLx, wNVDAx, etc.) → use Fluxion (only DEX with these pools).
• For BSB, ELSA, VOOI → use Fluxion (paired with USDT0).

Step 3: Token metadata

• For tokens in the registry, use their symbol directly.
• For unknown tokens, pass the contract address — the CLI resolves decimals on-chain.

Step 4: Build the swap

mantle-cli swap build-swap --provider <dex> --in <token> --out <token> \
  --amount <amount> --recipient <wallet> --json

• The CLI auto-resolves pool parameters (fee_tier, bin_step) from the pair registry.
• The CLI auto-discovers multi-hop routes when no direct pair exists.
• Just specify --in, --out, --amount, and --provider — the CLI does the rest.

Step 5: Allowance check and approve

• The swap router address is in the unsigned_tx.to field of the build-swap response.
• Check if the input token is approved for that router.
• If insufficient:

  mantle-cli swap approve --token <token> --spender <router_from_tx_to> --amount <exact_or_max> --owner <wallet> --json

Step 6: Sign and broadcast

• Pass the unsigned_tx object directly to the external signer.
• Do NOT add a `from` field.
• Do NOT modify any fields.

Step 7: Post-execution verification

• Re-read balances to confirm the swap completed.
• Compare observed output versus expected.

Common pitfalls

• `from` field: NEVER add from to unsigned_tx — breaks Privy and embedded signers.
• Manual routing: NEVER manually discover pools or split multi-hop into separate txs — use the CLI's built-in routing.
• Wrong pool parameters: NEVER manually specify --fee-tier or --bin-step for registered pairs — the CLI resolves them automatically.
• Merchant Moe version enum: the CLI handles this correctly (V1=0, V2.2=3); do NOT override.
• Missing approve: swaps require prior ERC-20 approval for the router contract.
• Multi-hop slippage: multi-hop routes have higher slippage risk — always get a quote first when possible.

Mantle Network Basics

Use this file for factual grounding when answering Mantle onboarding, difference, and developer-handoff questions. It supports a reference/onboarding skill rather than an execution workflow.

Source and freshness

• Primary source: https://docs.mantle.xyz/network/for-developers/quick-access
• Additional sources:
• https://docs.mantle.xyz/network/system-information/architecture
• https://docs.mantle.xyz/network/for-developers/resources-and-tooling/node-endpoints-and-providers
• Snapshot verified on: March 8, 2026
• If a user asks for the "latest" values or architecture status, re-check the official docs before answering.

How to use this reference

• Treat Core model, Mantle-Specific Differences, Developer Hints, and RPC reliability guidance as the stable-concepts layer.
• Treat Network details, Onboarding tools, contract links, and architecture notes as dated snapshots verified on March 8, 2026.
• If a question asks for "latest", "current", or rollout-status details, use this file to frame the answer and then live-verify before answering conclusively.

Core model

• Mantle is an Ethereum-aligned Layer 2 execution network.
• Users execute transactions on L2.
• Settlement/security assurances are anchored to Ethereum L1.
• Mantle is EVM-compatible and uses standard Ethereum tooling.
• Gas on Mantle is paid in MNT.

Mantle-Specific Differences

• MNT is the gas token, so developers should not assume ETH-funded wallets can transact on Mantle.
• Mantle is Ethereum-aligned, but fast L2 transaction inclusion is not the same thing as strongest L1-backed settlement/finality.
• Mantle-specific onboarding constants matter in practice:
• mainnet chainId: 5000
• Sepolia testnet chainId: 5003
• explorer domains and bridge links are Mantle-specific
• Per the Mantle architecture page snapshot verified on March 8, 2026, Mantle v2 Skadi is described as using an execution layer, a ZK validity proving module, and Ethereum data availability via blobs.
• Architecture rollout details can evolve, so treat fee behavior, throughput, and "latest architecture" questions as live-verify items.

Key Tokens on Mantle

CRITICAL: WETH (bridged ETH) EXISTS on Mantle. Do not confuse "MNT is the gas token" with "ETH doesn't exist on Mantle." ETH is bridged from L1 and is one of the most actively traded assets.

Common mistake to avoid: Claiming WETH doesn't exist on Mantle. It does — it's bridged ETH at 0xdEAD...1111, with ~125K ETH total supply and pools on every major DEX (Agni, Fluxion, Merchant Moe).

Network details (dated Quick Access snapshot)

Mainnet

• RPC URL: https://rpc.mantle.xyz
• WebSocket URL: wss://rpc.mantle.xyz
• Chain ID: 5000
• Token symbol: MNT
• Explorer: https://mantlescan.xyz/

Testnet (Sepolia)

• RPC URL: https://rpc.sepolia.mantle.xyz
• WebSocket URL: N/A (per Quick Access)
• Chain ID: 5003
• Token symbol: MNT
• Explorer: https://sepolia.mantlescan.xyz/

Onboarding tools (dated Quick Access snapshot)

Mainnet

• Bridge: https://app.mantle.xyz/bridge
• Recommended Solidity compiler: v0.8.23 or below
• Wrapped MNT: 0x78c1b0C915c4FAA5FffA6CAbf0219DA63d7f4cb8

Testnet (Sepolia)

• Faucet: https://faucet.sepolia.mantle.xyz/
• Third-party faucets:
• https://faucet.quicknode.com/mantle/sepolia
• https://thirdweb.com/mantle-sepolia-testnet/faucet
• Bridge: https://app.mantle.xyz/bridge?network=sepolia
• Recommended Solidity compiler: v0.8.23 or below
• Wrapped MNT: 0x19f5557E23e9914A18239990f6C70D68FDF0deD5
• Note: Mantle docs indicate Sepolia MNT can be requested directly from faucet (subject to limits).

Developer Hints

• Fund developer and test wallets with MNT, not ETH, before attempting transactions on Mantle.
• Use the official chain settings above instead of generic "custom EVM" assumptions.
• Mantle docs currently recommend Solidity v0.8.23 or below.
• Official public RPC endpoints are suitable for onboarding and light usage, but production or high-frequency workloads should use dedicated providers.
• For exact contract addresses, token mappings, and bridge-facing metadata, prefer the official address pages and token list links below over memory.
• When debugging UX issues, explain both:
• inclusion: the transaction is visible in an L2 block
• L1-backed settlement finality: the strongest settlement assurance once the L1-side conditions are satisfied

Contract and token source-of-truth

• L1 system contracts: https://docs.mantle.xyz/network/system-information/on-chain-system/key-l1-contract-address
• L2 system contracts: https://docs.mantle.xyz/network/system-information/off-chain-system/key-l2-contract-address
• Token list source-of-truth: https://token-list.mantle.xyz
• Bridge reference: https://bridge.mantle.xyz
• Token-list PR repo (for adding tokens): https://github.com/mantlenetworkio/mantle-token-lists

RPC reliability guidance

• Mantle docs state official RPC endpoints are rate-limited for stability.
• For high-frequency or production workloads, prefer dedicated provider endpoints.
• Provider directory: https://docs.mantle.xyz/network/for-developers/resources-and-tooling/node-endpoints-and-providers

Response rules for this skill

• Use absolute dates when quoting values from this file.
• Treat throughput, fee levels, ecosystem counts, and latency/finality windows as volatile.
• Distinguish:
• inclusion: transaction appears in L2 block.
• L1-backed settlement finality: strongest settlement assurance once L1 conditions are satisfied.
• For exact contract address lookups in execution contexts, cross-check with:
• Mantle contract address pages above, or
• $mantle-address-registry-navigator (if available in the runtime).

Difference checklist

When asked "what makes Mantle different", cover:

1. gas token and wallet funding expectations 2. inclusion versus L1-backed settlement/finality 3. current architecture snapshot versus live-verify items 4. onboarding constants such as chain IDs, bridge, explorer, and faucet 5. operational guidance such as RPC rate limits and provider selection

Allowance Risk Rules

Use these rules to classify spender approval exposure.

Inputs

• Token address
• Spender address
• Allowance raw value
• Token decimals (if known)
• is_unlimited flag from mantle-cli account allowances output (preferred when present)

Risk levels

• low
• Allowance is zero.
• Or allowance is tightly bounded and clearly below wallet balance/expected use.
• medium
• Allowance is non-zero and larger than immediate expected use, but still bounded.
• high
• Allowance is very large relative to expected use.
• Or allowance appears intentionally broad with unclear user intent.
• critical
• is_unlimited=true from tool output.
• Or allowance equals or is effectively near-max integer approval.
• Typical near-max detection: value >= 2^255.

Reporting rules

• Always include rationale text with each risk label.
• Mark spender trust status as unknown unless verified from mantle://registry/protocols or user-confirmed protocol.
• Highlight all high and critical approvals at top of summary.
• If token decimals are missing, classify using raw value and downgrade confidence.

Caveats

• Unlimited approval is not automatically malicious; it is an exposure signal.
• Risk scoring is heuristic and should be combined with protocol trust checks and intent context.

RPC Read-Only Workflow

Use this guide to gather wallet balances and allowances through mantle-cli read-only commands only. Do NOT enable or connect to the MCP server.

Required inputs

• Wallet address
• Network (mainnet or sepolia)
• Token set and spender set (user-provided or discovered)

Call sequence

1. mantle-cli registry validate <wallet> --json for wallet format checks. 2. mantle-cli chain info --json (and mantle-cli chain status --json when available) to confirm network context. 3. mantle-cli account balance <wallet> --json 4. mantle-cli account token-balances <wallet> --tokens <token1>,<token2>,... --json 5. mantle-cli account allowances <wallet> --pairs <token1>:<spender1>,<token2>:<spender2> --json 6. Optional metadata backfill: mantle-cli token info <token> --json for tokens with missing symbol/decimals.

Token and spender discovery

• Prefer explicit user scope first.
• If token scope is missing, read mantle://registry/tokens and select a bounded set for coverage.
• If spender scope is missing, read mantle://registry/protocols and extract known routers/pools.
• Use mantle-cli token resolve <symbol> --json for symbols outside the current scoped list before balance/allowance calls.
• If scope is still unknown, report that coverage is partial instead of inventing targets.

Normalization rules

• Prefer normalized values already returned by CLI JSON output.
• Convert raw values manually only when decimals are explicitly known.
• Keep both raw and normalized values in output.
• If decimals are unavailable, keep raw only and mark confidence lower.

Reliability checks

• Verify response chain/network matches requested input (mainnet or sepolia).
• Retry transient read failures with bounded attempts; do not switch to guessed tokens/spenders.
• Detect and report partial failures via tool-level partial flags and per-entry error fields.
• Include collected_at_utc values from CLI outputs in the final report.

Error Signature Map

Use this table to classify frequent read-path failures quickly.

RPC transport/connectivity

• Symptoms:
• timeout
• connection reset
• HTTP 429/503
• Likely causes:
• provider saturation
• rate limit
• unstable endpoint
• First actions:
• retry with backoff
• switch to fallback RPC
• reduce batch size/request rate

Call/revert errors

• Symptoms:
• execution reverted
• CALL_EXCEPTION
• empty return data where data expected
• Likely causes:
• wrong contract address
• wrong ABI/function selector
• invalid params or state preconditions
• First actions:
• verify target address/ABI
• dry-run minimal input
• decode revert data if available

Quote failures

• Symptoms:
• DEX aggregator quote returns null/error
• path not found
• amount out equals zero
• Likely causes:
• insufficient liquidity
• unsupported route/token pair
• wrong decimals/input units
• First actions:
• validate token decimals and amount scaling
• try smaller size
• try alternate route/source

Balance inconsistencies

• Symptoms:
• wallet balance differs across reads
• expected post-action balance not visible
• Likely causes:
• pending transactions
• nonce contention
• stale block tag/source lag
• First actions:
• compare latest vs pending
• inspect recent tx status
• re-read after bounded delay

Troubleshooting Playbook

Follow this sequence to keep diagnostics structured and repeatable.

Step 1: Reproduce and capture

• Re-run failing read with same parameters once.
• Record endpoint, method, params hash, timestamp (UTC), and exact error text.
• Record chain ID and block tag used.

Step 2: Branch by issue type

RPC exception branch

1. Check endpoint health and rate-limit signals. 2. Retry with bounded backoff. 3. Switch to fallback endpoint. 4. Compare outcomes across endpoints.

Quote failure branch

1. Verify token addresses and decimals. 2. Verify input amount scaling. 3. Probe smaller notional size. 4. Try alternate liquidity source.

Balance mismatch branch

1. Compare reads at latest and pending. 2. Check for unconfirmed tx and nonce conflicts. 3. Reconcile token decimals and symbol/address mapping. 4. Re-read at consistent block context.

Step 3: Conclude with bounded claim

• State likely root cause as hypothesis plus confidence.
• Provide smallest next action.
• If unresolved after bounded retries, escalate with captured evidence.

Escalation package

• Full raw error strings
• Endpoint list tested
• Request fingerprints (without private keys/secrets)
• Timestamped observations
• What was ruled out

Risk Checklist

Apply all checks before execution intent is approved.

Input completeness

• operation_type present
• chain/environment present
• token and amount fields present
• target contract/router/pool address present

Fail if any mandatory field is missing.

Slippage check

• Compare proposed slippage against user-defined cap.
• If no user cap exists, apply default from risk-threshold-guidance.md.
• Fail when cap exceeded.

Liquidity depth check

• Estimate price impact from quote/simulation context.
• Warn on moderate impact, fail on severe impact (threshold-driven).
• If liquidity data unavailable, set warn with reduced confidence.

Address safety check

• Verify all addresses against trusted registry/tooling.
• Flag unknown, suspicious, or blacklisted addresses.
• Fail on blacklisted/explicitly flagged addresses.

Allowance scope check

• Detect approvals broader than required for intended amount.
• Warn on broad allowances.
• Fail if operation requires new unlimited approval without user confirmation.

Gas and deadline sanity

• Check gas estimate reasonableness versus recent baseline.
• Check transaction deadline is not stale and not excessively long.
• Warn or fail according to threshold profile.

Finalization rule

• Any fail in critical categories => final verdict block.
• No fail and at least one warn => final verdict warn.
• All checks pass => final verdict pass.

Risk Threshold Guidance

Use user-specified parameters first. Use defaults only when user constraints are absent.

Default thresholds (recommended baseline)

• Slippage cap:
• Warn: > 0.5%
• Fail: > 1.0%
• Estimated price impact:
• Warn: > 2%
• Fail: > 5%
• Deadline horizon:
• Warn: > 20 minutes
• Fail: > 60 minutes
• Gas deviation from rolling baseline:
• Warn: > 20%
• Fail: > 40%

Address trust

• pass: trusted and verified source
• warn: unknown but not explicitly flagged
• fail: flagged, blacklisted, or malformed address

Allowance policy

• pass: existing allowance fits intended spend scope
• warn: allowance materially larger than intended spend
• fail: new or existing near-unlimited approval without explicit user approval

Near-unlimited heuristic:

• raw allowance >= 2^255

Confidence policy

• high: all required signals present and consistent
• medium: one non-critical signal missing
• low: key signals missing (for example no liquidity data or unresolved address provenance)

If confidence is low, downgrade verdict one level toward caution (pass -> warn, warn -> block).

Deployment Checklist

Run this checklist before preparing an external deployment handoff.

Environment checks

• Confirm target environment (mainnet or testnet).
• Confirm expected chain ID and RPC endpoint.
• Confirm deployer address and sufficient native balance for gas.

Build checks

• Confirm compiler version and optimizer settings.
• Confirm bytecode reproducibility from clean build.
• Confirm ABI and metadata artifacts exist.
• Confirm constructor args are complete and correctly encoded.

Safety checks

• Confirm no unresolved TODO/debug flags in source.
• Confirm external dependency addresses are network-correct.
• Confirm ownership/admin initialization values are intentional.

Cost checks

• Estimate deployment gas.
• Estimate native fee using current gas pricing.
• Compare estimate against max cost constraint.

Final gate

• If any required check fails: stop deployment.
• If all checks pass: produce an unsigned deployment handoff for an external signer/wallet.

Verification Playbook

Use this workflow to plan or validate verification of externally deployed contracts on Mantle explorers.

Required inputs

• deployed contract address
• contract source path and contract name
• compiler version
• optimizer enabled/runs
• constructor arguments (raw and encoded)
• linked library addresses (if any)

Steps

1. Confirm deployed bytecode exists at target address. 2. Prepare verification payload for explorer API/UI submission (or provide manual submission instructions when tooling is unavailable). 3. Poll verification status from explorer responses until success/failure/timeout. 4. Record verification link or identifier.

Common failures and fixes

• Compiler mismatch:
• Rebuild with exact compiler version used at deployment.
• Optimizer mismatch:
• Match enable flag and run count exactly.
• Constructor args mismatch:
• Re-encode with precise argument order and types.
• Metadata/library mismatch:
• Provide fully qualified library mapping.

Evidence requirements

• Keep full request payload snapshot (excluding secrets).
• Keep explorer response body and timestamp.
• Do not claim the agent submitted deployment/verification transactions; execution happens externally.
• Do not claim "verified" without explicit success response.

Development Checklist

Run this checklist before handing a Mantle contract project to deployment planning.

Product and environment checks

• Confirm the contract's purpose, users, and privileged roles.
• Confirm target environment (mainnet or testnet).
• Confirm whether the contract must be upgradeable or immutable.
• Confirm whether the contract will hold assets, mint tokens, bridge funds, or control admin actions.

Mantle-specific integration checks

• Confirm every external contract address is correct for the requested Mantle environment.
• Confirm native gas assumptions use MNT.
• Confirm any bridge, oracle, DEX, vault, or system dependency is explicitly named and environment-correct.
• Confirm frontend or backend integrations know which events, functions, and initialization values they depend on.

Contract design checks

• Confirm the chosen OpenZeppelin base contracts and access-control model.
• Confirm constructor or initializer inputs are complete and intentional.
• Confirm pause, emergency, or recovery flows are specified when relevant.
• Confirm upgrade authorization and storage-layout constraints are understood when proxies are used.

Quality checks

• Confirm unit, integration, and failure-path test expectations.
• Confirm the highest-risk behaviors that need focused review.
• Confirm no unresolved TODO, placeholder address, or ambiguous permission remains.

Handoff gate

• If any required item is unclear, stop and resolve it before deployment planning.
• If all items are clear, produce a development brief and hand off to $mantle-smart-contract-deployer.

OpenZeppelin MCP Handoff

Use OpenZeppelin MCP whenever the user needs actual smart contract writing or implementation guidance for a Mantle project.

Route to OpenZeppelin MCP for

• Solidity contract scaffolding or code generation
• OpenZeppelin inheritance and extension choices
• Ownable, AccessControl, token, proxy, upgrade, governor, or security module usage
• constructor, initializer, or storage-layout implementation details
• contract refactors tied to OpenZeppelin patterns

Provide this handoff context

• Mantle environment (mainnet or testnet)
• contract purpose and user flows
• asset model and token standards involved
• admin and upgradeability requirements
• external Mantle dependencies and known addresses
• deployment constraints or verification requirements already known

Expected return from OpenZeppelin MCP

• recommended contract modules and inheritance plan
• implementation notes or code guidance
• security-sensitive decisions to review
• inputs needed for testing and deployment

Boundary

• OpenZeppelin MCP handles contract authoring guidance.
• mantle-smart-contract-developer handles Mantle-specific framing, readiness checks, and handoff into $mantle-smart-contract-deployer.

Simulation Backends

Choose backend by availability, fidelity, and reproducibility requirements. These backends are external and must be run outside the CLI toolchain.

Backend options

Local fork (Anvil or equivalent)

• Best for deterministic local replay and rapid iteration.
• Requires archive-capable RPC and correct fork block configuration.
• Good for deep debugging with custom call sequences.

Managed simulation API (Tenderly or equivalent)

• Best for quick hosted simulation with rich traces.
• Good for team workflows and sharable simulation artifacts.
• Depends on provider uptime and account/project configuration.

Selection heuristic

1. Use local fork when you need deterministic reproducibility or custom pre-state setup. 2. Use managed simulator when you need speed, traces, and collaboration. 3. If one backend fails, request one retry on an alternate backend before declaring inconclusive.

Minimum captured fields

• backend name
• network/chain ID
• simulation timestamp (UTC)
• transaction payload
• success/revert status
• gas estimate
• decoded events/logs (if available)
• state diff summary

Inconclusive conditions

• backend error without trace
• unresolved calldata decoding
• missing token metadata needed for user-facing summary

Return status: inconclusive and do_not_execute_reason when any inconclusive condition exists.

WYSIWYS Template

Use this template to translate simulation output into plain-language signing expectations.

Required extraction

• Assets debited from user wallet
• Assets credited to user wallet
• Fee estimate in native token
• Approval changes (if any)
• Critical caveats (slippage, deadline, unresolved uncertainty)

Plain-language format

If this transaction is broadcast:
- You will spend: <amount token>
- You will receive at least: <amount token>
- Estimated network fee: <amount native token>
- Additional approval change: <description or none>

Rules

• Use "at least" wording when outcome depends on slippage.
• If output token amount is uncertain, explicitly say so.
• If simulation reverted, do not provide optimistic receive amount.
• Never present simulation as guaranteed final execution.

Revert wording template

Simulation failed before execution.
- Likely failure point: <function/step>
- Observed error: <decoded message or raw revert data>
- Action: do_not_execute until issue is resolved.