CornerStone MCP x402 Skill (for Agents)

This skill gives you (the agent) a set of tools to: create and manage Aptos and EVM wallets, check balances, and call x402-paid MCP tools (stock prediction, backtest, bank linking, agent/borrower scores). Payment is automatic — when a paid tool returns 402, the skill signs, verifies, settles, and retries transparently. You just call the tool; the result comes back.

---

Quick-start workflow

Follow this sequence on first use, then skip to the tool you need:

1. Check wallets → call get_wallet_addresses (no args).
2. If empty → call create_aptos_wallet then create_evm_wallet.
3. Fund → call credit_aptos_wallet (Aptos faucet) and fund_evm_wallet (EVM faucet instructions).
4. Tell the user to whitelist the returned addresses at https://arnstein.ch/flow.html.
5. Check balance → call balance_aptos (must have USDC for predictions/backtests) and/or balance_evm (must have ETH for bank linking).
6. Use paid tools → run_prediction, run_backtest, link_bank_account, or score tools.

Important: Paid tools will fail with a wallet/whitelist error if the address has not been funded and whitelisted. Always verify wallets and balances first.

---

Tool reference

Wallet management tools (local)

get_wallet_addresses

• Args: none
• Returns: { aptos: [{ address, network }], evm: [{ address, network }] } — may be empty arrays.
• When to use: Always call first before any wallet or paid tool action. Determines what exists.
• Decision: If both arrays are empty → create wallets. If only one is empty → create the missing one. If both have entries → proceed to balance check or paid tools.

create_aptos_wallet

• Args: { force?: boolean, network?: "testnet" | "mainnet" } — defaults: force=false, network=testnet.
• Returns: { success, address, network, message } or { success: false, message, addresses } if wallet exists and force=false.
• When to use: When get_wallet_addresses returns empty aptos array, or user requests a new wallet.
• Error handling: If success: false and wallet already exists, either use the existing wallet or retry with force: true to add another.

create_evm_wallet

• Args: { force?: boolean, network?: "testnet" | "mainnet" } — defaults: force=false, network=testnet.
• Returns: { success, address, network, message } or { success: false, message, addresses }.
• Same pattern as create_aptos_wallet.

credit_aptos_wallet

• Args: { amount_octas?: number } — default 100,000,000 (= 1 APT).
• Returns on devnet: { success: true, address } (programmatic faucet funded).
• Returns on testnet: { success: true, address, faucet_url } (instructions only; no programmatic faucet).
• Prerequisite: Aptos wallet must exist (create_aptos_wallet first).
• Note: Funded APT is for gas; tools pay in USDC (~6¢). The user may need to acquire testnet USDC separately.

fund_evm_wallet

• Args: none
• Returns: { success: true, address, faucet_url, message } (manual funding instructions).
• Prerequisite: EVM wallet must exist (create_evm_wallet first).
• Note: Returns a Base Sepolia faucet URL. The user must fund manually; there is no programmatic faucet.

Balance tools (local)

balance_aptos

• Args: none
• Returns: { address, balances: { usdc, apt } } or { error }.
• When to use: Before calling run_prediction, run_backtest, or score tools to confirm sufficient USDC.

balance_evm

• Args: { chain?: string } — default "base". Supported: base, baseSepolia, ethereum, polygon, arbitrum, optimism.
• Returns: { address, chain, balance, symbol } or { error }.
• When to use: Before calling link_bank_account to confirm sufficient ETH on Base Sepolia.
• Note: For testnet tools, use chain: "baseSepolia".

Paid MCP tools (x402 — payment handled automatically)

All paid tools accept both Aptos and EVM payment. The skill picks the best option or follows PREFERRED_PAYMENT_ORDER. You never see 402 errors — just call the tool and get the result or an error message.

run_prediction

• Args: { symbol: string, horizon?: number } — symbol is a stock ticker (e.g. "AAPL"), horizon is days (default 30).
• Returns: Prediction result object (forecast data, confidence intervals, etc.) or { error }.
• Cost: ~6¢ USDC (Aptos or EVM).
• Prerequisite: Funded + whitelisted Aptos or EVM wallet.
• Example call: run_prediction({ symbol: "AAPL", horizon: 30 })

run_backtest

• Args: { symbol: string, startDate?: string, endDate?: string, strategy?: string } — dates in "YYYY-MM-DD", strategy defaults to "chronos".
• Returns: Backtest result (returns, drawdown, sharpe, etc.) or { error }.
• Cost: ~6¢ USDC.
• Example call: run_backtest({ symbol: "TSLA", startDate: "2024-01-01", endDate: "2024-12-31", strategy: "chronos" })

link_bank_account

• Args: none
• Returns: { link_token } or account ID for Plaid bank linking, or { error }.
• Cost: ~5¢ (EVM/Base).
• Prerequisite: Funded + whitelisted EVM wallet (Base Sepolia for testnet).

get_agent_reputation_score

• Args: { agent_address?: string, payer_wallet?: string } — both optional; uses the configured wallet if omitted.
• Returns: { reputation_score: number } (e.g. 100) or 403 if not allowlisted, or { error }.
• Cost: ~6¢ via x402, or free with lender credits (pass payer_wallet).

get_borrower_score

• Args: { agent_address?: string, payer_wallet?: string } — same pattern.
• Returns: { score: number } (100 base; higher with bank linked) or { error }.
• Cost: ~6¢ via x402, or free with lender credits.

get_agent_reputation_score_by_email

• Args: { email: string, payer_wallet?: string } — resolves email to allowlisted agent.
• Returns: { reputation_score: number } or { error }.
• Prerequisite: SCORE_BY_EMAIL_ENABLED must be set on the server. Higher fee.

get_borrower_score_by_email

• Args: { email: string, payer_wallet?: string } — same pattern.
• Returns: { score: number } or { error }.
• Prerequisite: SCORE_BY_EMAIL_ENABLED must be set on the server. Higher fee.

---

Decision tree for common tasks

"Run a prediction for X"

get_wallet_addresses
  → aptos empty? → create_aptos_wallet → credit_aptos_wallet → tell user to whitelist
  → aptos exists? → balance_aptos
    → has USDC? → run_prediction({ symbol: "X", horizon: 30 })
    → no USDC? → tell user to fund USDC, provide address

"Link a bank account"

get_wallet_addresses
  → evm empty? → create_evm_wallet → fund_evm_wallet → tell user to whitelist
  → evm exists? → balance_evm({ chain: "baseSepolia" })
    → has ETH? → link_bank_account
    → no ETH? → fund_evm_wallet (returns faucet URL)

"Get my scores"

get_wallet_addresses
  → has aptos or evm? → get_agent_reputation_score + get_borrower_score
  → neither? → create wallets first, whitelist, then query

---

Error handling

Error pattern	Meaning	What to do
"No Aptos wallet"	Wallet file missing	Call create_aptos_wallet
"No EVM wallet"	Wallet file missing	Call create_evm_wallet
"already exist. Use force: true"	Wallet exists, not overwriting	Use existing wallet, or pass force: true to add another
"Payment verification failed"	Insufficient funds or wrong asset	Check balance; tell user to fund the wallet
"No Aptos wallet configured" / "No EVM wallet configured"	Paid tool needs wallet that doesn't exist	Create the missing wallet type
"Unsupported chain"	Invalid chain name for balance_evm	Use one of: base, baseSepolia, ethereum, polygon, arbitrum, optimism
"timed out after 300s"	MCP call took too long	Retry once; the server may be under load
"403" or "not allowlisted"	Wallet not whitelisted	Tell user to whitelist address at https://arnstein.ch/flow.html

---

Setup (for the human installing this skill)

1. Install: npm install from repo root. Copy .env.example to .env.
2. Configure: Set wallet paths (APTOS_WALLET_PATH, EVM_WALLET_PATH or EVM_PRIVATE_KEY).
3. Wallets: Create via tools (create_aptos_wallet, create_evm_wallet) or CLI (node src/setup-aptos.js, node src/setup.js). Fund and whitelist all addresses at https://arnstein.ch/flow.html.

---

CLI commands (from repo root)

Task	Command
Generate Aptos wallet	npm run setup:aptos
Generate EVM wallet	npm run setup
Show addresses for whitelist	npm run addresses
Credit Aptos (devnet)	npm run credit:aptos (set APTOS_FAUCET_NETWORK=devnet)
EVM balance	npm run balance -- <chain>
Transfer ETH/tokens	npm run transfer -- <chain> <to> <amount> [tokenAddress]
Swap tokens (Odos)	npm run swap -- <chain> <fromToken> <toToken> <amount>
Run skill demo	npx cornerstone-agent "Run a 30-day prediction for AAPL"
Attest Aptos wallet	npm run attest:aptos
Attest EVM wallet	npm run attest:evm

---

Source: FinTechTonic/autonomous-agent