MCP server

Endpoint: https://papertrade-yield.pages.dev/mcp

It is an MCP Streamable HTTP server, stateless and read-only. There are no sessions, no cookies and no auth. Every tool reads public Papertrade and HyperEVM data. No tool signs or sends anything.

Transport behavior#

Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are supported. initialize echoes the client's version when supported, otherwise answers 2025-06-18. Capabilities are { "tools": { "listChanged": false } }. resources/list, resources/templates/list and prompts/list return empty lists.

Errors follow JSON-RPC: -32700 parse error (HTTP 400), -32600 invalid request, -32601 unknown method, -32602 unknown tool or bad params. Invalid tool arguments are reported as a normal result with isError: true so the model can correct itself. Requests over 64 KB return 413. Calls to tools/call are limited to 60 per minute per client IP and return 429 with Retry-After and JSON-RPC code -32000 beyond that.

Tools#

All tools carry readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: true. Results contain a text summary in content and the same data in structuredContent.

get_staking_stats#

PAPER staking stats. Current PAPER staking state on Papertrade: total supply, staked amount and share, undistributed staker rewards, minimum stake, the current mint rate (PAPER minted per $1 of loss), liquidity context, and the realized USDC yield per 1M PAPER per day over 24h, 7d and 30d. PAPER has no market price, so yield is quoted per 1M PAPER, not as a percentage. Read only.

This tool takes no arguments.

Structured output fields: generatedAt, paperSupply, paperStaked, stakedShare, pendingRewardsUsd, minimumStakePaper, accRewardPerShareUsdPerPaper, mintRate, onFlatBranch, trackedLpUsd, cumulativeRewardsUsd, yieldWindows, method, pricing, contracts.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_apr#

Realized yield and implied APR. Realized staking yield for PAPER over 24h, 7d and 30d as USDC per 1M PAPER per day. PAPER has no market price, so a percentage APR exists only for a price you assume: pass assumedPaperPriceUsd to get a simple (non-compounding) implied APR for that price. Without a price, impliedAprPercent is null. Read only.

Structured output fields: assumedPaperPriceUsd, windows, method, pricing.

{
  "type": "object",
  "properties": {
    "assumedPaperPriceUsd": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "A PAPER price in USD to test. It is an assumption, not a market quote."
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d"
      ],
      "description": "Trailing window of realized yield to use."
    }
  },
  "additionalProperties": false
}

get_yield_history#

Hourly staking reward history. Hourly history of USDC distributed to PAPER stakers, newest last: reward in USD, mean staked PAPER, USDC per PAPER and the pace as USDC per 1M PAPER per day, for the trailing number of hours. Buckets before staking rewards began are omitted. Read only.

Structured output fields: hours, points, totalRewardsUsd, cumulativeRewardsUsd.

{
  "type": "object",
  "properties": {
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 720,
      "default": 48,
      "description": "How many trailing hourly buckets to return."
    }
  },
  "additionalProperties": false
}

get_claims_activity#

On-chain claims activity. USDC that stakers claimed on chain (PaperStaking Claimed events on HyperEVM) over the trailing 1 to 72 hours, bucketed per hour, with unique claimers and the largest claim. Claiming is a choice, so this differs from USDC distributed. Read only.

Structured output fields: hours, totalClaimedUsd, claims, uniqueClaimers, largestClaimUsd, buckets.

{
  "type": "object",
  "properties": {
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 72,
      "default": 24
    }
  },
  "additionalProperties": false
}

get_wallet_staking#

Wallet stake and rewards. Staking position of one wallet: staked PAPER (net of the wallet's Staked and Unstaked history), unstaked PAPER balance and pending USDC reward (both read on chain now), lifetime USDC claimed, and the ten most recent staking events. Amounts are in PAPER and USDC; raw 18-decimal values are included. Read only: it never needs or accepts a key.

Structured output fields: address, paperStaked, paperUnstakedBalance, pendingRewardUsd, lifetimeClaimedUsd, raw, historyComplete, recentEvents, readAt.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x-prefixed 20-byte HyperEVM wallet address. Read only: this is a lookup, nothing is signed."
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

project_rewards#

Projected staking rewards calculator. Calculator: what a PAPER position would earn if the realized pace of a trailing window simply continued. Give either paperAmount (PAPER you hold or would stake) or lossUsd (a hypothetical trading loss, converted to PAPER at today's mint rate; liquidations mint on the full loss, normal closes on 98%). The result is an extrapolation of history, not a forecast: the pace and the mint rate both move. Add assumedPaperPriceUsd for an implied APR. Read only.

Structured output fields: paperAmount, lossUsd, mintRate, window, windowComplete, usdPer1MPaperPerDay, days, projectedUsdPerDay, projectedUsdOverDays, projectedUsdPerYear, breakEvenDays, impliedAprPercent, caveat.

{
  "type": "object",
  "properties": {
    "paperAmount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "PAPER staked. Give this or lossUsd."
    },
    "lossUsd": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Hypothetical loss in USD. Give this or paperAmount."
    },
    "liquidated": {
      "type": "boolean",
      "default": false,
      "description": "With lossUsd: the position was liquidated rather than closed at a loss."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "default": 30
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d"
      ],
      "description": "Trailing window of realized yield to use."
    },
    "assumedPaperPriceUsd": {
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

plan_staking_action#

Plan a stake, unstake or claim (unsigned). Builds an UNSIGNED plan for staking, unstaking or claiming PAPER staking rewards: preflight checks against the wallet's real balance, staked amount and pending reward, the EIP-712 type and domain the wallet would be asked to sign, and a link to the app where the owner signs in their own wallet. This tool never signs, never submits and never moves funds; the nonce and deadline are only allocated when the owner signs. Read only.

Structured output fields: unsigned, signed, submitted, action, address, amountPaper, amountRaw, preflight, typedData, howToSign, signUrl, note.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "stake",
        "unstake",
        "claim"
      ]
    },
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x-prefixed 20-byte HyperEVM wallet address. Read only: this is a lookup, nothing is signed."
    },
    "amountPaper": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]{1,18})?$",
      "description": "PAPER amount as a decimal string. Required for stake and unstake, ignored for claim."
    }
  },
  "required": [
    "action",
    "address"
  ],
  "additionalProperties": false
}

Examples#

Realized yield with an assumed price:

curl -s https://papertrade-yield.pages.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_apr","arguments":{"assumedPaperPriceUsd":0.01,"window":"7d"}}}'

Project rewards for a loss, assuming it was liquidated:

curl -s https://papertrade-yield.pages.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"project_rewards","arguments":{"lossUsd":500,"liquidated":true,"days":30}}}'

Plan a claim without signing it:

curl -s https://papertrade-yield.pages.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"plan_staking_action","arguments":{"action":"claim","address":"0x0000000000000000000000000000000000000001"}}}'

The plan contains unsigned: true, signed: false, submitted: false, preflight checks, the EIP-712 typed data to be signed, and a link to the web app where the wallet owner signs.

Inspect it#

npx @modelcontextprotocol/inspector --cli https://papertrade-yield.pages.dev/mcp --transport http --method tools/list

View this page as markdown