Wayfinder#

DeFi trading, yield strategies, and portfolio management powered by poetry run wayfinder Paths.

Pre-Flight Check#

Before running any commands, verify that poetry run wayfinder Paths is installed and reachable:

bash

# SDK location (override by setting WAYFINDER_SDK_PATH)
export WAYFINDER_SDK_PATH="${WAYFINDER_SDK_PATH:-$HOME/wayfinder-paths-sdk}"

# Check if wayfinder-paths-sdk directory exists
if [ ! -d "$WAYFINDER_SDK_PATH" ]; then
  echo "ERROR: wayfinder-paths-sdk is not installed at: $WAYFINDER_SDK_PATH"
  echo "Set WAYFINDER_SDK_PATH or run the First-Time Setup below."
  exit 1
fi

# Config path (override by setting WAYFINDER_CONFIG_PATH)
export WAYFINDER_CONFIG_PATH="${WAYFINDER_CONFIG_PATH:-$WAYFINDER_SDK_PATH/config.json}"

# Check if the config exists
if [ ! -f "$WAYFINDER_CONFIG_PATH" ]; then
  echo "ERROR: config not found at $WAYFINDER_CONFIG_PATH. Run the First-Time Setup below."
  exit 1
fi

# Check if the CLI is functional
cd "$WAYFINDER_SDK_PATH"
if ! poetry run wayfinder --help > /dev/null 2>&1; then
  echo "ERROR: poetry run wayfinder CLI is not working. Run 'cd $WAYFINDER_SDK_PATH && poetry install' to fix."
  exit 1
fi

echo "poetry run wayfinder Paths is installed and ready."

If either check fails, follow the First-Time Setup instructions below before proceeding.

Quick Start#

First-Time Setup#

Important: The SDK must be installed from GitHub via git clone. Do NOT install from PyPI ( pip install wayfinder-paths will not work).

Before starting: You need a Wayfinder API key (format: wk_...). Get one at https://strategies.wayfinder.ai. The guided setup will prompt you for this key.

bash

# Clone wayfinder-paths-sdk from GitHub (required — do NOT pip install)
export WAYFINDER_SDK_PATH="${WAYFINDER_SDK_PATH:-$HOME/wayfinder-paths-sdk}"
if [ ! -d "$WAYFINDER_SDK_PATH" ]; then
  git clone https://github.com/WayfinderFoundation/wayfinder-paths-sdk.git "$WAYFINDER_SDK_PATH"
fi

cd "$WAYFINDER_SDK_PATH"
poetry install

# Run guided setup (creates/updates config.json + local dev wallets + MCP config)
# You will need your API key from https://strategies.wayfinder.ai (format: wk_...)
python3 scripts/setup.py

Wallet security:

• NEVER output private keys or seed phrases into the conversation. These are secrets — they must stay on the machine, never in chat.
• For a long-running bot, prefer a seed phrase stored in your backend/secret manager rather than generating random wallets on the server.
• On first-time setup, the user should retrieve the seed phrase directly from their machine or secret manager. Only offer to display the seed phrase if the user explicitly confirms they cannot access the machine to retrieve it themselves.
• See references/setup.md for detailed wallet setup instructions.

Verify Setup#

bash

export WAYFINDER_SDK_PATH="${WAYFINDER_SDK_PATH:-$HOME/wayfinder-paths-sdk}"
export WAYFINDER_CONFIG_PATH="${WAYFINDER_CONFIG_PATH:-$WAYFINDER_SDK_PATH/config.json}"
cd "$WAYFINDER_SDK_PATH"
poetry run wayfinder resource wayfinder://strategies
poetry run wayfinder resource wayfinder://wallets
poetry run wayfinder resource wayfinder://balances/main

Command Reference#

All commands should be run from $WAYFINDER_SDK_PATH and require WAYFINDER_CONFIG_PATH (default: $WAYFINDER_SDK_PATH/config.json). All responses return {"ok": true, "result": {...}} on success or {"ok": false, "error": {"code": "...", "message": "..."}} on failure.

---

resource — Read MCP resources by URI#

Read-only access to adapters, strategies, wallets, balances, tokens, and Hyperliquid market data via URI-based resources. Use --list to see all available resources and templates.

Asset/data sourcing rule: When the user asks you to look up token/pool/market/protocol data, first use Wayfinder’s adapter/strategy discovery resources ( poetry run wayfinder resource wayfinder://adapters, wayfinder://adapters/{name}, wayfinder://strategies, wayfinder://tokens/*). Only fall back to other methods if Wayfinder doesn’t expose the required data or the user explicitly asks.

bash

# List all available resources and templates
poetry run wayfinder resource --list

Static Resources

URIDescriptionwayfinder://adaptersList all adapters with capabilitieswayfinder://strategiesList all strategies with adapter dependencieswayfinder://walletsList all configured walletswayfinder://hyperliquid/pricesAll Hyperliquid mid priceswayfinder://hyperliquid/marketsPerp market metadata, funding rates, and asset contextswayfinder://hyperliquid/spot-assetsSpot asset metadatabash

poetry run wayfinder resource wayfinder://adapters
poetry run wayfinder resource wayfinder://strategies
poetry run wayfinder resource wayfinder://wallets
poetry run wayfinder resource wayfinder://hyperliquid/prices
poetry run wayfinder resource wayfinder://hyperliquid/markets
poetry run wayfinder resource wayfinder://hyperliquid/spot-assets

Resource Templates

URI TemplateDescriptionwayfinder://adapters/{name}Describe a single adapter (e.g. moonwell_adapter)wayfinder://strategies/{name}Describe a single strategy (e.g. stablecoin_yield_strategy)wayfinder://wallets/{label}Get a single wallet by labelwayfinder://balances/{label}Enriched multi-chain balances for a walletwayfinder://activity/{label}Recent transaction activity for a walletwayfinder://tokens/search/{chain_code}/{query}Fuzzy token search (hits /tokens/fuzzy/) — ALWAYS use this firstwayfinder://tokens/resolve/{query}Resolve a token by known ID (hits /tokens/detail/) — only use with IDs from searchwayfinder://tokens/gas/{chain_code}Native gas token for a chain (ETH, HYPE) — use for native tokenswayfinder://hyperliquid/{label}/statePerp positions + PnL for a walletwayfinder://hyperliquid/{label}/spotSpot balances on Hyperliquid for a walletwayfinder://hyperliquid/prices/{coin}Mid price for a single coinwayfinder://hyperliquid/book/{coin}Order book for a coin

Token lookup order — always search or use gas endpoint first:

bash

# 1. For native gas tokens (ETH, HYPE): use the gas endpoint
poetry run wayfinder resource wayfinder://tokens/gas/ethereum    # ETH on Ethereum
poetry run wayfinder resource wayfinder://tokens/gas/base        # ETH on Base
poetry run wayfinder resource wayfinder://tokens/gas/hyperevm    # HYPE on HyperEVM

# 2. For ERC20 tokens: ALWAYS fuzzy search first
poetry run wayfinder resource wayfinder://tokens/search/base/usdc
poetry run wayfinder resource wayfinder://tokens/search/arbitrum/eth
poetry run wayfinder resource wayfinder://tokens/search/ethereum/weth

# 3. Then resolve with the exact ID from search results
poetry run wayfinder resource wayfinder://tokens/resolve/usd-coin-base

bash

poetry run wayfinder resource wayfinder://adapters/moonwell_adapter
poetry run wayfinder resource wayfinder://strategies/stablecoin_yield_strategy
poetry run wayfinder resource wayfinder://wallets/main
poetry run wayfinder resource wayfinder://balances/main
poetry run wayfinder resource wayfinder://activity/main
poetry run wayfinder resource wayfinder://hyperliquid/main/state
poetry run wayfinder resource wayfinder://hyperliquid/main/spot
poetry run wayfinder resource wayfinder://hyperliquid/prices/ETH
poetry run wayfinder resource wayfinder://hyperliquid/book/ETH

---

wallets — Manage wallets and discover positions#

Create, annotate, and discover cross-protocol positions. Use resource wayfinder://wallets to list wallets and resource wayfinder://wallets/{label} to get a single wallet.

ParameterTypeRequiredDefaultNotesaction``"create" | "annotate" | "discover_portfolio"Yes——labelstringcreate—Must be non-empty; duplicate labels are idempotentwallet_labelstringannotate, discover_portfolio—Or use wallet_address``wallet_addressstringNo—Alternative to wallet_label``protocolstringannotate—Protocol name for annotationannotate_actionstringannotate—Action being annotatedtoolstringannotate—Tool name for annotationstatusstringannotate—Status for annotationchain_idstringNo——detailsstring (JSON)No—Extra metadata for annotationprotocolsstring (JSON)No—Filter discover_portfolio to specific protocolsparallelboolNofalseRequired if querying >= 3 protocols without a protocols filterinclude_zero_positionsboolNofalseInclude empty positions in portfolio

Supported protocols for discover_portfolio: hyperliquid, hyperlend, moonwell, boros, pendle.

bash

poetry run wayfinder wallets --action create --label my_new_strategy
poetry run wayfinder wallets --action discover_portfolio --wallet_label main --parallel
poetry run wayfinder wallets --action discover_portfolio --wallet_label main --protocols '["hyperliquid","moonwell"]'

Validations:

• create: label must be non-empty. Duplicate labels return the existing wallet (idempotent).
• annotate/ discover_portfolio: must resolve a wallet address from wallet_label or wallet_address.
• annotate: all of protocol, annotate_action, tool, status are required.
• discover_portfolio with >= 3 protocols requires parallel=true or an explicit protocols filter (returns requires_confirmation otherwise).

---

quote_swap — Get a swap/bridge quote (read-only)#

Returns a quote for swapping or bridging tokens. No on-chain effects.

ParameterTypeRequiredDefaultNoteswallet_labelstringYes—Must resolve to a wallet with an addressfrom_tokenstringYes—Token ID from search results (e.g. usd-coin-base). Always search first — do not guess.to_tokenstringYes—Token ID from search results. Always search first.amountstringYes—Human-readable amount (e.g. "500"). Must be positive, Decimal-parseable, and > 0 after scaling to token decimalsslippage_bpsintNo50Slippage tolerance in basis points (50 = 0.5%)recipientstringNo—Defaults to sender addressinclude_calldataboolNofalseInclude raw calldata in response

Always resolve token IDs before calling quote_swap. Run poetry run wayfinder resource wayfinder://tokens/search/<chain>/<symbol> for each token first, then use the exact ID from the result. Do not pass raw symbols or guessed symbol-chain strings — they may resolve incorrectly or fail.

Note: Native gas tokens (e.g., unwrapped ETH) may fail in swaps with from_token_address: null. Use the wrapped ERC20 version instead (e.g., WETH). Search for it: resource wayfinder://tokens/search/<chain>/weth.

Bridging to a new chain for the first time: the wallet needs native gas on the destination chain before it can do anything. Bridge the native gas token (e.g. ETH) to the destination chain first, then bridge or swap for the target token. Use the native token IDs from the supported-chains table below (e.g. ethereum-base for ETH on Base).

• Use the native token IDs from the supported-chains table below when bridging gas (e.g. ethereum-base for ETH on Base, plasma-plasma for PLASMA on Plasma).

bash

poetry run wayfinder quote_swap --wallet_label main --from_token usd-coin-base --to_token ethereum-base --amount 500
poetry run wayfinder quote_swap --wallet_label main --from_token "USDC-base" --to_token "ETH-base" --amount 1000 --slippage_bps 100

Errors: not_found (wallet), invalid_wallet, token_error, invalid_token (missing chain_id/address), invalid_amount, quote_error.

---

execute — Execute on-chain transactions#

Execute swaps, token sends, or Hyperliquid deposits. This broadcasts transactions and can move real funds.

ParameterTypeRequiredDefaultNoteskind``swap | send | hyperliquid_depositYes—Operation typewallet_labelstringYes—Must resolve to a wallet with private keyamountstringYes—Human-readable amount (e.g. "500")from_tokenstringswap—Source token ID. Always search first.to_tokenstringswap—Destination token ID. Always search first.slippage_bpsintNo50Swap only; basis pointsdeadline_secondsintNo300Swap onlyrecipientstringsend—Recipient addresstokenstringsend—Token ID (or "native" with chain_id). Always search first.chain_idstringNo—Required for send when token="native"``forceflagNofalseDo not rely on this as a “dry-run vs live” gate. Treat execute as live and require explicit user confirmation before calling it.

Hyperliquid deposit validations (critical):

• Amount must be >= 5 USDC (deposits below 5 are lost on the bridge).
• Hard-codes: token = Arbitrum USDC, recipient = HYPERLIQUID_BRIDGE_ADDRESS, chain = Arbitrum (42161).

Additional runtime validations:

• Wallet must have both address and private_key_hex.
• Token resolution must succeed (chain_id + token address required).
• Swap quotes must return a best_quote with calldata.
• For USDT-style tokens, a zero-allowance reset transaction is sent before approval.

bash

# Swap
poetry run wayfinder execute --kind swap --wallet_label main --from_token usd-coin-base --to_token ethereum-base --amount 500

# Send tokens
poetry run wayfinder execute --kind send --wallet_label main --token usd-coin-base --recipient 0x... --amount 100

# Hyperliquid deposit (min 5 USDC)
poetry run wayfinder execute --kind hyperliquid_deposit --wallet_label main --amount 100

---

hyperliquid — Wait for Hyperliquid deposits/withdrawals#

Wait for deposits or withdrawals to settle on Hyperliquid. For read-only queries (user state, prices, order books), use the resource command with Hyperliquid URIs.

ParameterTypeRequiredDefaultNotesaction``"wait_for_deposit" | "wait_for_withdrawal"Yes——wallet_labelstringNo—Or use wallet_address``wallet_addressstringNo—Alternative to wallet_label``expected_increasestringNo—Expected USDC increase for deposittimeout_sintNo120Timeout for wait_for_deposit``poll_interval_sintNo5Poll interval for wait actionslookback_sintNo5For wait_for_withdrawal``max_poll_time_sintNo900Max wait for wait_for_withdrawal (15 min)bash

poetry run wayfinder hyperliquid --action wait_for_deposit --wallet_label main --expected_increase 100
poetry run wayfinder hyperliquid --action wait_for_withdrawal --wallet_label main

Read-only queries via resources:

bash

# Perp positions + PnL
poetry run wayfinder resource wayfinder://hyperliquid/main/state

# Spot balances
poetry run wayfinder resource wayfinder://hyperliquid/main/spot

# All mid prices
poetry run wayfinder resource wayfinder://hyperliquid/prices

# Single coin price
poetry run wayfinder resource wayfinder://hyperliquid/prices/ETH

# Market metadata + funding rates
poetry run wayfinder resource wayfinder://hyperliquid/markets

# Spot asset metadata
poetry run wayfinder resource wayfinder://hyperliquid/spot-assets

# Order book
poetry run wayfinder resource wayfinder://hyperliquid/book/ETH

---

hyperliquid_execute — Hyperliquid trading operations#

Place/cancel orders, update leverage, and withdraw USDC. These operations are live and can place real orders / move real funds.

ParameterTypeRequiredDefaultNotesaction``place_order | cancel_order | update_leverage | withdraw | spot_to_perp_transfer | perp_to_spot_transferYes——wallet_labelstringYes—Must resolve to wallet with private keycoinstringplace_order, cancel_order, update_leverage—Or use asset_id. Strips -perp/ _perp suffixes automaticallyasset_idstringNo—Direct asset ID (alternative to coin)is_spotstringNo—true for spot orders, false for perp. Must be explicit for place_order.order_type``market | limitNomarket—is_buystringplace_order—true or false``sizestringNo—Mutually exclusive with usd_amount; coin unitsusd_amountstringNo—Mutually exclusive with size; USD amountusd_amount_kindstringwhen usd_amount is used—notional or margin``leveragestringwhen usd_amount_kind=margin; update_leverage—Must be positivepricestringlimit orders—Must be positiveslippagefloatNo0.01Market orders only; 0–0.25 (25% cap)reduce_onlyflagNofalse``--reduce_only / --no-reduce_only``cloidstringNo—Client order IDorder_idstringcancel_order—Or use cancel_cloid``cancel_cloidstringNo—Alternative to order_id for cancelis_crossflagNotrue``--is_cross / --no-is_cross``amount_usdcstringwithdraw, transfers—USDC amount for withdraw or transfersbuilder_fee_tenths_bpstringNo—Falls back to config defaultforceflagNofalseDo not rely on this as a “dry-run vs live” gate. Treat hyperliquid_execute as live and require explicit user confirmation before calling it.

Key validations for place_order:

• Exactly one of size or usd_amount (not both, not neither).
• If usd_amount is used, usd_amount_kind is required.
• If usd_amount_kind=margin, then leverage is required.
• Limit orders require price > 0.
• After lot-size rounding, size must still be > 0.
• Builder fee is mandatory (auto-configured; approval is auto-submitted if needed).

bash

# Market buy
poetry run wayfinder hyperliquid_execute --action place_order --wallet_label main --coin ETH --is_buy true --usd_amount 200 --usd_amount_kind margin --leverage 5

# Spot buy
poetry run wayfinder hyperliquid_execute --action place_order --wallet_label main --coin HYPE --is_spot true --is_buy true --usd_amount 20

# Limit sell
poetry run wayfinder hyperliquid_execute --action place_order --wallet_label main --coin ETH --is_buy false --size 0.1 --price 4000 --order_type limit

# Close position (reduce-only)
poetry run wayfinder hyperliquid_execute --action place_order --wallet_label main --coin ETH --is_buy false --size 0.5 --reduce_only

# Update leverage
poetry run wayfinder hyperliquid_execute --action update_leverage --wallet_label main --coin ETH --leverage 5

# Cancel order
poetry run wayfinder hyperliquid_execute --action cancel_order --wallet_label main --coin ETH --order_id 12345

# Withdraw USDC
poetry run wayfinder hyperliquid_execute --action withdraw --wallet_label main --amount_usdc 100

# Transfer USDC between spot and perp wallets
poetry run wayfinder hyperliquid_execute --action spot_to_perp_transfer --wallet_label main --amount_usdc 50
poetry run wayfinder hyperliquid_execute --action perp_to_spot_transfer --wallet_label main --amount_usdc 50

---

polymarket — Polymarket market + account reads#

Read-only access to Polymarket markets, prices, order books, and user status.

Tradability filter: a market can be “found” but not tradable. Filter for enableOrderBook, acceptingOrders, active, closed != true, and non-empty clobTokenIds.

ParameterTypeRequiredDefaultNotesaction``status | search | trending | get_market | get_event | price | order_book | price_history | bridge_status | open_ordersYes——wallet_labelstringNo—Resolves account from config; required for open_orders``wallet_addressstringNo—Alternative to wallet_label for account-based readsaccountstringNo—Direct account address (alternative to wallet inputs)include_ordersboolNotrue``status onlyinclude_activityboolNofalse``status onlyactivity_limitintNo50``status onlyinclude_tradesboolNofalse``status onlytrades_limitintNo50``status onlypositions_limitintNo500``status onlymax_positions_pagesintNo10``status onlyquerystringsearch—Query string for fuzzy market searchlimitintNo10``search, trending``pageintNo1``search``keep_closed_marketsboolNofalse``search``rerankboolNotrue``search``offsetintNo0``trending``market_slugstringget_market—Market slugevent_slugstringget_event—Event slugtoken_idstringprice, order_book, price_history—Polymarket CLOB token id (optional for open_orders filter)side``BUY | SELLNoBUY``price onlyintervalstringNo"1d"``price_history onlystart_tsintNo—price_history only (unix seconds)end_tsintNo—price_history only (unix seconds)fidelityintNo—price_history only

Action-specific requirements:

• status, bridge_status: require an account (via --account, --wallet_address, or --wallet_label).
• open_orders: requires --wallet_label and a wallet with private_key_hex in config.json (Level-2 auth). Optional: --token_id to filter.

bash

# Search markets
poetry run wayfinder polymarket --action search --query "bitcoin above 100k" --limit 5

# User status (positions + balances)
poetry run wayfinder polymarket --action status --wallet_label main

# CLOB order book
poetry run wayfinder polymarket --action order_book --token_id 123456

---

polymarket_execute — Polymarket execution (bridge + orders)#

Execute Polymarket actions (bridging and trading). This command is live (no dry-run flag).

ParameterTypeRequiredDefaultNotesaction``bridge_deposit | bridge_withdraw | buy | sell | close_position | place_limit_order | cancel_order | redeem_positionsYes——wallet_labelstringYes—Wallet must include address and private_key_hex in configfrom_chain_idintNo137``bridge_deposit onlyfrom_token_addressstringNoPolygon USDCbridge_deposit onlyamountfloatbridge_deposit—Amount of USDC to depositrecipient_addressstringNosenderbridge_deposit onlyamount_usdcefloatbridge_withdraw—Amount of USDC.e to withdrawto_chain_idintNo137``bridge_withdraw onlyto_token_addressstringNoPolygon USDCbridge_withdraw onlyrecipient_addrstringNosenderbridge_withdraw onlytoken_decimalsintNo6Bridge token decimalsmarket_slugstringNo—Used by buy, sell, close_position``outcomestring | intNo"YES"Used with market_slug (e.g. YES/ NO)token_idstringNo—Alternative to market_slug for buy, sell, place_limit_order``amount_usdcfloatbuy—Buy amount in USDCsharesfloatsell—Shares to sellside``BUY | SELLNoBUY``place_limit_order onlypricefloatplace_limit_order—Limit price (0–1)sizefloatplace_limit_order—Order size (shares)post_onlyboolNofalse``place_limit_order onlyorder_idstringcancel_order——condition_idstringredeem_positions—Required for redeem_positions; also accepted by close_position as a fallback

Approvals + API creds: handled automatically before order placement (idempotent).

Collateral: Polymarket CLOB trading collateral is USDC.e on Polygon, not native Polygon USDC. Use bridge_deposit / bridge_withdraw to convert. These methods prefer a fast on-chain BRAP swap on Polygon when possible (sender == recipient); otherwise they fall back to the Polymarket Bridge service ( method: "polymarket_bridge" in the result) and you can monitor via polymarket --action bridge_status.

Trade semantics:

• buy uses amount_usdc as collateral ($) to spend
• sell uses shares as shares to sell

Always require explicit user confirmation before running polymarket_execute.

bash

# Bridge USDC -> USDC.e collateral (Polymarket)
poetry run wayfinder polymarket_execute --action bridge_deposit --wallet_label main --amount 10

# Buy shares by market slug + outcome
poetry run wayfinder polymarket_execute --action buy --wallet_label main --market_slug "some-market-slug" --outcome YES --amount_usdc 2

# Close a position (sells full size; resolves token_id from market slug)
poetry run wayfinder polymarket_execute --action close_position --wallet_label main --market_slug "some-market-slug" --outcome YES

---

run_strategy — Strategy lifecycle management#

Run strategy actions: check status, analyze, quote, deposit, update, withdraw, or exit.

ParameterTypeRequiredDefaultNotesstrategystringYes—Strategy directory name; must have manifest.yaml``action``status | analyze | snapshot | policy | quote | deposit | update | withdraw | exitYes——amount_usdcfloatNo1000.0Read-only analysis: hypothetical deposit for analyze, snapshot, quote``amountstringNo—Generic amount parameter (strategy-specific)main_token_amountstringdeposit—Actual deposit: amount of strategy's deposit tokengas_token_amountfloatNo0.0Actual deposit: optional gas token amount

Amount parameter rules:

• For read-only analysis ( analyze, snapshot, quote): use --amount_usdc
• For actual deposits ( deposit): use --main_token_amount (required) + optionally --gas_token_amount
• The deposit token varies by strategy (USDC on Base for stablecoin_yield, USDC on Arbitrum for boros_hype, etc.)

bash

poetry run wayfinder resource wayfinder://strategies
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action status
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action analyze --amount_usdc 100
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action quote --amount_usdc 100
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action deposit --main_token_amount 100 --gas_token_amount 0.01
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action update
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action withdraw
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action exit

Errors: invalid_request (empty strategy), not_found (missing manifest), not_supported (strategy lacks the method), strategy_error (runtime exception).

Note: withdraw liquidates positions but funds stay in the strategy wallet. exit transfers funds from the strategy wallet back to the main wallet. These are separate steps.

---

run_script — Execute sandboxed Python scripts#

Run a local Python script in a subprocess. Scripts must live inside the runs directory ( $WAYFINDER_RUNS_DIR or .wayfinder_runs/).

ParameterTypeRequiredDefaultNotesscript_pathstringYes—Must be .py, must exist, must be inside the runs directoryargsstringNo—Arguments passed to the script (JSON list)timeout_sintNo600Clamped to min 1 secondenvstringNo—Additional env vars for subprocess (JSON object)wallet_labelstringNo—For profile annotationforceflagNofalseDo not rely on this as a “dry-run vs live” gate. Prefer implementing --dry-run / --force inside your script and passing it via --args.

Validations:

• Script path must resolve to inside the runs directory (sandboxed — no arbitrary file execution).
• Must be a .py file.
• Must exist on disk.
• Output is truncated to 20,000 chars.

bash

# Recommended: implement --dry-run / --force in your script and pass it via --args
poetry run wayfinder run_script --script_path .wayfinder_runs/my_flow.py --args '["--dry-run"]' --wallet_label main
poetry run wayfinder run_script --script_path .wayfinder_runs/my_flow.py --args '["--force"]' --wallet_label main

# With timeout
poetry run wayfinder run_script --script_path .wayfinder_runs/my_flow.py --wallet_label main --timeout_s 120

---

Config Structure#

Config is loaded from $WAYFINDER_CONFIG_PATH (default: $WAYFINDER_SDK_PATH/config.json).

json

{
  "system": {
    "api_base_url": "https://strategies.wayfinder.ai/api/v1",
    "api_key": "wk_..."
  },
  "strategy": {
    "rpc_urls": {
      "1": ["https://eth.llamarpc.com"],
      "42161": ["https://arb1.arbitrum.io/rpc"],
      "8453": ["https://mainnet.base.org"],
      "999": ["https://rpc.hyperliquid.xyz/evm"]
    }
  },
  "wallets": [
    {
      "label": "main",
      "address": "0x...",
      "private_key_hex": "0x..."
    }
  ],
  "ccxt": {
    "aster": { "apiKey": "", "secret": "" },
    "binance": { "apiKey": "", "secret": "" }
  }
}

• system.api_key falls back to $WAYFINDER_API_KEY env var.
• Most write operations require a wallet entry with address + private_key_hex.

Available Strategies#

StrategyStatusChainTokenRiskDescriptionbasis_trading_strategystableHyperliquidUSDCMediumDelta-neutral funding rate capture with matched spot/perp positionsboros_hype_strategystableArbitrum + HyperEVM + HyperliquidHYPE/USDCMediumMulti-leg HYPE yield with fixed-rate funding lock via Boroshyperlend_stable_yield_strategystableHyperEVMUSDT0LowStablecoin yield optimization on HyperLend with rotation policymoonwell_wsteth_loop_strategystableBaseUSDC/WETH/wstETHMedium-HighLeveraged wstETH carry trade via Moonwell loopingstablecoin_yield_strategywipBaseUSDCLowAuto-rotates across best stablecoin pools on Baseprojectx_thbill_usdc_strategywipHyperEVMTHBILL/USDCMediumConcentrated liquidity market making on ProjectX (V3 fork)

Reference: references/strategies.md

Available Adapters#

AdapterProtocolCapabilitiesbalance_adapterEVM walletsbalance.read, transfer.main_to_strategy, transfer.strategy_to_main, transfer.send``boros_adapterBoros (Arbitrum)market.read, market.quote, position.open, position.close, collateral.deposit, collateral.withdraw``brap_adapterCross-chain swapsswap.quote, swap.execute, swap.compare_routes, bridge.quote, gas.estimate``ccxt_adapterCentralized exchanges (CCXT)exchange.factory``hyperlend_adapterHyperLend (HyperEVM)market.stable_markets, market.assets_view, market.rate_history, lending.lend, lending.unlend``hyperliquid_adapterHyperliquid DEXmarket.read, market.meta, market.funding, market.candles, market.orderbook, order.execute, order.cancel, position.manage, transfer, withdraw``ledger_adapterLocal bookkeepingledger.read, ledger.record, ledger.snapshot``moonwell_adapterMoonwell (Base)lending.lend, lending.unlend, lending.borrow, lending.repay, collateral.set, collateral.remove, rewards.claim, position.read, market.apy, market.collateral_factor``multicall_adapterEVM batch callsmulticall.aggregate``pendle_adapterPendlependle.markets.read, pendle.market.snapshot, pendle.swap.quote, pendle.swap.execute, pendle.convert.quote, pendle.positions.database, and morepolymarket_adapterPolymarketmarket.read, market.search, market.orderbook, market.candles, position.read, order.execute, order.cancel, bridge.deposit, bridge.withdraw``pool_adapterDeFi Llamapool.read, pool.discover``projectx_adapterProjectX (V3 fork)projectx.pool.overview, projectx.positions.list, projectx.liquidity.mint, projectx.liquidity.increase, projectx.liquidity.decrease, projectx.fees.collect, projectx.swap.exact_in``token_adapterToken metadatatoken.read, token.price, token.gas``uniswap_adapterUniswap V3uniswap.liquidity.add, uniswap.liquidity.increase, uniswap.liquidity.remove, uniswap.fees.collect, uniswap.position.get, uniswap.positions.list, uniswap.fees.uncollected, uniswap.pool.get

Reference: references/adapters.md

Token ID Format — ALWAYS SEARCH FIRST#

CRITICAL: NEVER guess or construct token IDs. Always look up the correct token using the appropriate endpoint before using it in any command.

Three token endpoints — know which to use:

• tokens/search → fuzzy search (hits /blockchain/tokens/fuzzy/) — always use this first for ERC20 tokens
• tokens/resolve → exact lookup (hits /blockchain/tokens/detail/) — only use with an ID you got from search
• tokens/gas → native gas tokens (hits /blockchain/tokens/gas/) — use for ETH, HYPE, and other native tokens

Token IDs use <coingecko_id>-<chain_code> format (NOT symbol-chain):

• usd-coin-base (USDC on Base) — NOT usdc-base
• ethereum-arbitrum (ETH on Arbitrum) — NOT ETH-arbitrum
• usdt0-arbitrum (USDT on Arbitrum) — NOT USDT-arbitrum
• hyperliquid-hyperevm (HYPE on HyperEVM) — NOT HYPE-hyperevm

You cannot reliably guess coingecko IDs from token symbols. For example, ETH's coingecko ID is ethereum, USDC's is usd-coin, HYPE's is hyperliquid. These are not derivable from the symbol alone.

Native gas tokens are best discovered via tokens/gas/<chain_code>. Use the table below as a convenient reference, but prefer tokens/gas when in doubt.

Valid chain codes (common): ethereum, base, arbitrum, polygon, bsc, avalanche, plasma, hyperevm. Note: mainnet is NOT a valid chain code — use ethereum instead.

Supported chains#

ChainIDCodeSymbolNative token IDEthereum1ethereumETHethereum-ethereumBase8453baseETHethereum-baseArbitrum42161arbitrumETHethereum-arbitrumPolygon137polygonPOLpolygon-ecosystem-token-polygonBSC56bscBNBbinancecoin-bscAvalanche43114avalancheAVAXavalanche-avalanchePlasma9745plasmaPLASMAplasma-plasmaHyperEVM999hyperevmHYPEhyperliquid-hyperevm

Before every swap, send, or token operation:

bash

# For native gas tokens (ETH, HYPE):
poetry run wayfinder resource wayfinder://tokens/gas/<chain_code>

# For ERC20 tokens — REQUIRED: fuzzy search first
poetry run wayfinder resource wayfinder://tokens/search/<chain_code>/<symbol>
# Then use the exact token ID from the search result

Sizing for Perp Orders#

When a user says "$X at Yx leverage", clarify:

• --usd_amount_kind margin = $X is collateral (notional = X * leverage)
• --usd_amount_kind notional = $X is position size

--usd_amount and --size are mutually exclusive. When using --usd_amount with --usd_amount_kind margin, --leverage is required.

Safety#

• NEVER output private keys or seed phrases into the conversation. These are secrets that must stay on the machine. Only offer to display a seed phrase if the user explicitly confirms they cannot access the machine to retrieve it themselves.

• Execution commands are live. Require explicit user confirmation before running execute, hyperliquid_execute, polymarket_execute, or any script that broadcasts transactions.

• NEVER guess or fabricate token IDs. Before any token operation (swap, send, quote, balance check):

  • For native gas tokens (ETH, HYPE): use poetry run wayfinder resource wayfinder://tokens/gas/<chain_code>
  • For ERC20 tokens: use poetry run wayfinder resource wayfinder://tokens/search/<chain_code>/<query> (fuzzy search) and use the exact token ID from the result
  • Do not construct IDs by combining symbols with chain names — the coingecko ID is unpredictable. Do not call tokens/resolve with a guessed ID — it hits a different API than search.

• Bridging to a new chain (first time): bridge native gas to the destination chain first (use the supported-chains table or tokens/gas/<chain_code>), then bridge/swap for the target asset.

• Start with small test amounts.

• Withdraw and exit are separate steps: withdraw liquidates positions, exit transfers funds home.

• Hyperliquid deposits must be >= 5 USDC — amounts below 5 are lost on the bridge.

• Market order slippage is capped at 25% ( --slippage 0.25).

• Scripts are sandboxed to the runs directory — no arbitrary file execution.

Common Workflows#

Check Before Trading#

bash

poetry run wayfinder resource wayfinder://balances/main
# ALWAYS look up tokens first — never guess IDs
poetry run wayfinder resource wayfinder://tokens/search/base/usdc   # Search for USDC → get token ID from result
poetry run wayfinder resource wayfinder://tokens/gas/base            # Get native ETH on Base
# Use the exact token IDs from the lookup results
poetry run wayfinder resource wayfinder://hyperliquid/prices/ETH
poetry run wayfinder quote_swap --wallet_label main --from_token usd-coin-base --to_token ethereum-base --amount 1000

Deploy a Strategy#

bash

poetry run wayfinder resource wayfinder://strategies
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action status
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action deposit --main_token_amount 100 --gas_token_amount 0.01
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action update

Open a Hyperliquid Position#

bash

poetry run wayfinder resource wayfinder://hyperliquid/main/state
poetry run wayfinder hyperliquid_execute --action update_leverage --wallet_label main --coin ETH --leverage 5
poetry run wayfinder hyperliquid_execute --action place_order --wallet_label main --coin ETH --is_buy true --usd_amount 200 --usd_amount_kind margin --leverage 5

Wind Down Everything#

bash

poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action withdraw
poetry run wayfinder run_strategy --strategy stablecoin_yield_strategy --action exit

Custom Scripts via the Coding Interface#

For any operation that goes beyond a single CLI command, you SHOULD write a custom Python script. The wayfinder-paths-sdk provides a full coding interface — use it whenever you need multi-step flows, conditional logic, batched operations, or protocol combinations.

When to Write a Script#

• Multi-step atomic flows — operations that must succeed together
• Custom logic — conditional execution based on market state
• Batched operations — multiple protocol interactions in sequence
• Protocol combinations — bridging multiple adapters in one flow
• Complex calculations — position sizing, rebalancing, PnL analysis
• Anything the user asks that isn't a single CLI call

Script Location#

All generated scripts must be saved to .wayfinder_runs/ inside the SDK directory:

text

$WAYFINDER_SDK_PATH/.wayfinder_runs/my_script.py

This directory is sandboxed — run_script only executes scripts inside it. Create it if it doesn't exist:

bash

mkdir -p "$WAYFINDER_SDK_PATH/.wayfinder_runs"

Referencing the SDK Source#

Before writing any script, pull the detailed reference docs for the adapter or strategy you're working with. The SDK ships comprehensive skill docs covering method signatures, gotchas, unit conventions, and execution patterns.

Use the reference script (bash or PowerShell):

bash

# List available topics
./wayfinder/scripts/pull-sdk-ref.sh --list

# Pull docs for specific adapters (supports multiple topics)
./wayfinder/scripts/pull-sdk-ref.sh moonwell
./wayfinder/scripts/pull-sdk-ref.sh boros hyperliquid
./wayfinder/scripts/pull-sdk-ref.sh strategies

# Pull everything
./wayfinder/scripts/pull-sdk-ref.sh --all

# Check the pinned SDK version
./wayfinder/scripts/pull-sdk-ref.sh --version

# Override with a specific commit
./wayfinder/scripts/pull-sdk-ref.sh --commit abc123 moonwell

powershell

# Windows
.\wayfinder\scripts\pull-sdk-ref.ps1 moonwell
.\wayfinder\scripts\pull-sdk-ref.ps1 -All
.\wayfinder\scripts\pull-sdk-ref.ps1 -Version
.\wayfinder\scripts\pull-sdk-ref.ps1 -Commit abc123 moonwell

Available topics: strategies, setup, boros, brap, hyperlend, hyperliquid, polymarket, moonwell, pendle, uniswap, projectx, data

The SDK ref is tracked in wayfinder/sdk-version.md (default: main). The pull script checks out that ref when reading docs, then restores the SDK to its previous state.

Always run this before writing a script — the docs cover critical details like:

• Exact method signatures and required parameters
• Unit conventions (raw base units vs human-readable, wei vs native)
• Gotchas (e.g., unlend() takes mToken amounts not underlying, withdrawal cooldowns, funding sign conventions)
• Execution patterns and safety rails
• Token/contract addresses

You can also read the adapter source code directly:

text

$WAYFINDER_SDK_PATH/wayfinder_paths/adapters/          # All adapter implementations
$WAYFINDER_SDK_PATH/wayfinder_paths/mcp/scripting.py   # get_adapter() helper
$WAYFINDER_SDK_PATH/wayfinder_paths/strategies/        # Strategy implementations

Quick Start#

python

#!/usr/bin/env python3
import asyncio
from wayfinder_paths.mcp.scripting import get_adapter
from wayfinder_paths.adapters.moonwell_adapter import MoonwellAdapter

async def main():
    adapter = get_adapter(MoonwellAdapter, "main")  # Auto-wires config + signing
    success, result = await adapter.lend(mtoken="0x...", amount=100_000_000)
    print(f"Result: {result}" if success else f"Error: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Testing Workflow#

Always test before live execution. Follow this workflow:

1. Write the script to .wayfinder_runs/

2. Safe run — run the script in a non-fund-moving mode first (recommended: implement --dry-run / --force in your script and pass it via --args): bash

   cd "$WAYFINDER_SDK_PATH"
   poetry run wayfinder run_script --script_path .wayfinder_runs/my_script.py --args '["--dry-run"]' --wallet_label main
   
   

3. Review the output. Verify the operations, amounts, and addresses are correct.

4. Live execution — only after confirming the safe run looks right, run with --force: bash

   poetry run wayfinder run_script --script_path .wayfinder_runs/my_script.py --args '["--force"]' --wallet_label main
   
   

Never skip the safe-run step for scripts that move funds.

Reference: references/coding-interface.md — Full adapter API reference, examples, and patterns

Protocol References#

• references/setup.md — First-time setup, configuration, and wallet management
• references/strategies.md — Strategy details, parameters, and workflows
• references/adapters.md — Adapter capabilities and method signatures
• references/coding-interface.md — Custom Python scripting with adapters
• references/hyperliquid.md — Hyperliquid trading, deposits, funding
• references/polymarket.md — Polymarket markets, bridging, and trading
• references/ccxt.md — Centralized exchanges (Aster/Binance/etc.) via CCXT (use carefully)
• references/moonwell.md — Moonwell lending, mToken addresses, gotchas
• references/pendle.md — Pendle PT/YT markets, swap execution
• references/boros.md — Boros fixed-rate markets, rate locking
• references/uniswap.md — Uniswap V3 LP positions and fee collection
• references/projectx.md — ProjectX (V3 fork) LP positions, swaps, and strategy notes
• references/tokens-and-pools.md — Token IDs, pool discovery, balance reads
• references/hyperlend.md — HyperLend lending, supply/withdraw flows

Error Handling#

All errors return structured JSON: {"ok": false, "error": {"code": "...", "message": "...", "details": ...}}.

Error Categories#

Validation Errors — bad input, fixable by the caller

Error CodeMeaningCommon CausesUser-Facing Guidanceinvalid_requestMissing or invalid required parametersOmitted action, empty strategy, missing token_id for balance queryTell the user which parameter is missing and show the correct command formatinvalid_walletWallet missing address or private_key_hexWallet label exists but entry is incomplete; read-only wallet used for executionAsk the user to check their config.json wallet entry has both fieldsinvalid_tokenToken resolution failed — missing chain_id or contract address after lookupTypo in token ID, token not indexed, ambiguous symbol without chain qualifierSuggest running resource wayfinder://tokens/search/<chain>/<query> and show the closest matchesinvalid_amountAmount not parseable, not positive, or zero after decimal scalingNon-numeric string, negative value, amount like 0.000000001 that rounds to 0 for a low-decimal tokenShow the parsed value and the token's decimals so the user understands the rounding

Resource Errors — something doesn't exist

Error CodeMeaningCommon CausesUser-Facing Guidancenot_foundDirectory, manifest, wallet, or resource not foundStrategy name typo, adapter not installed, wallet label doesn't match configList available resources ( resource wayfinder://strategies) so the user can pick the right namenot_supportedStrategy does not implement the requested actionCalling withdraw on a strategy that only supports status/ depositShow which actions the strategy does support (from its manifest)requires_confirmationOperation needs explicit user confirmation before proceedingdiscover_portfolio across >= 3 protocols without --parallel flagExplain the operation scope and ask the user to confirm or pass --parallel

API & Integration Errors — upstream service failures

Error CodeMeaningCommon CausesUser-Facing Guidancetoken_errorToken adapter API call failedWayfinder API down, network timeout, invalid API keyCheck API key validity; retry after a moment; show the raw error message from detailsquote_errorSwap/bridge quote generation failedNo liquidity for pair, amount too small for routing, bridge route unavailableSuggest trying a different amount, checking if the pair is supported, or using a different routebalance_errorBalance query failedRPC node down, rate-limited, invalid chain_idRetry; if persistent, check RPC URL configurationactivity_errorActivity/transaction history query failedIndexer lag, unsupported chain for activityInform user the history service may be temporarily unavailableprice_errorPrice lookup failedToken not priced by CoinGecko, API rate limitNote that the token may be too new or illiquid for price data; balances are still valid without prices

Execution Errors — on-chain failures

Error CodeMeaningCommon CausesUser-Facing Guidanceexecutor_errorOn-chain transaction failedInsufficient gas, contract revert, nonce conflict, allowance issueShow the revert reason if available; check gas balance; for USDT-style tokens, mention the zero-allowance resetstrategy_errorStrategy runtime exceptionUnhandled edge case in strategy code, external dependency failure mid-executionShow the exception message; suggest checking status before retrying

Error Details Object#

The details field varies by error code and may contain:

FieldPresent OnDescriptionparameter``invalid_requestThe specific parameter that failed validationwallet_label``invalid_wallet, not_foundThe wallet label that was looked upquery``invalid_tokenThe token query that failed resolutioncandidates``invalid_tokenFuzzy match candidates when availableraw_amount``invalid_amountThe original amount string providedscaled_amount``invalid_amountThe amount after decimal scaling (shows why it became zero)decimals``invalid_amountToken decimals used for scalingtx_hash``executor_errorTransaction hash if the tx was submitted before failingrevert_reason``executor_errorDecoded revert reason from the contractstrategy``strategy_error, not_supportedStrategy namesupported_actions``not_supportedList of actions the strategy does implementprotocols``requires_confirmationThe protocols that would be queriedupstream_error``token_error, quote_error, balance_error, activity_error, price_errorRaw error message from the upstream service

Presenting Errors to Users#

When an error is returned, follow this pattern:

1. Translate the code — don't show raw error codes. Map to plain language (e.g., invalid_token -> "I couldn't find that token").
2. Include the actionable fix — every error above has a recovery path. Always tell the user what to do next.
3. Show relevant details — if details.candidates exists, list the closest token matches. If details.revert_reason exists, explain what the contract rejected.
4. Offer to retry — for transient errors ( token_error, balance_error, quote_error, activity_error, price_error), offer to retry. For validation errors, show the corrected command.

Common User-Facing Issues#

SymptomError CodeResolution"Missing config"not_foundRun setup or create config.json manually"strategy_wallet not configured"invalid_walletAdd wallet with matching label to config.json"Minimum deposit"invalid_amountCheck strategy minimum requirements (e.g., Hyperliquid >= 5 USDC)"Insufficient gas"executor_errorFund wallet with native gas token for the target chain"Token not found"invalid_tokenUse resource wayfinder://tokens/search/<chain>/<query> to find the correct coingecko ID"No quote available"quote_errorTry a different amount, check pair liquidity, or use an alternative route"Nonce too low"executor_errorA previous transaction is pending; wait or speed it up"Allowance reset needed"executor_errorFor USDT-style tokens, the CLI auto-resets allowance — retry if it was a transient RPC issue"Rate limited"token_error / balance_errorWait a few seconds and retry the request

Best Practices#

Security#

1. Never share private keys or commit config.json
2. Start with small test amounts
3. Use dedicated wallets per strategy for isolation
4. Verify addresses before large transfers
5. Use stop losses for leverage trading

Trading#

1. Always quote before executing swaps
2. Specify chain for lesser-known tokens
3. Consider gas costs (use Base for small amounts)
4. Check balance before trades
5. Use limit orders for better prices on Hyperliquid