# FlexYield

> One API key and one bill for multi-chain JSON-RPC access, with automatic multi-provider failover — at prices below going direct. No wallet, no crypto required.

FlexYield is a unified RPC gateway: point your application at a single endpoint and every JSON-RPC 2.0 request is routed to the best healthy upstream provider, with automatic failover and per-key usage metering. Accounts are email-based, plans are card-billed, and a live dashboard shows volume, latency, and spend per API key.

## Getting started

1. Sign up (free tier included): https://flexyield.io/registration/new
2. Create an API key in the dashboard — the plaintext token is shown exactly once.
3. Relay JSON-RPC requests:

    curl -X POST https://flexyield.io/rpc/eth_mainnet \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber"}'

## Agent Skill

Full agent instructions (keys, budgets, fleet pattern, MCP): https://flexyield.io/skill.md

## Supported chains

Relay to any of these with POST https://flexyield.io/rpc/{chain}:

- arbitrum_one — Arbitrum One
- base_mainnet — Base Mainnet
- eth_mainnet — Ethereum Mainnet
- optimism_mainnet — OP Mainnet
- polygon_pos — Polygon PoS
- solana_mainnet — Solana Mainnet

## Data API (beyond raw RPC)

Same bearer API key and metering as /rpc. Requires a paid plan (free-tier
keys receive error -32010). Status: premium data upstreams are
onboarding — these endpoints answer 503 until a data-capable provider is live.

- GET https://flexyield.io/data/{chain}/balances/{address} — native balance (all chains); ERC-20 token balances on chains with a data-capable upstream
- GET https://flexyield.io/data/{chain}/history/{address} — recent asset transfers, newest first (chains with a data-capable upstream)
- GET https://flexyield.io/toolbox/gas/{chain} — EIP-1559 gas recommendations (slow/standard/fast) computed from the multi-provider pool, EVM chains, 1 unit/call, every tier; also the get_gas_prices MCP tool. Toolbox services can be disabled per account — a disabled service answers -32012 (HTTP 403) with the enable path; an optional per-service monthly cap answers -32014 (HTTP 429) once reached.
- GET https://flexyield.io/toolbox/tx/{chain}/{hash} — transaction status on any supported chain (confirmed/failed/pending/unknown; confirmations + gas on EVM, slot + commitment on Solana), 2 units/call (computed per hash); also the get_tx_status MCP tool.
- GET https://flexyield.io/toolbox/ens/resolve/{name} and /toolbox/ens/reverse/{address} — on-chain ENS resolution (Ethereum mainnet), 1 unit/call; also the resolve_ens MCP tool. Reverse records are self-declared — forward-verify before trusting.
- GET https://flexyield.io/toolbox/prices?symbols=eth,btc — USD prices read on-chain from Chainlink aggregator feeds (no third-party price API; symbols eth, btc, link — more on request), honest stale flags, 1 unit/call; also the get_token_prices MCP tool.
- GET https://flexyield.io/toolbox/abi/{chain}/{address} — verified contract ABI + name from Sourcify's open dataset (unverified answers verified:false with the fix path); POST /toolbox/decode/{chain}/{address} with data=0x… decodes calldata to function signature + arguments. 1 unit each; MCP tools get_abi, decode_calldata.
- GET https://flexyield.io/toolbox/utils/checksum/{address} · /toolbox/utils/convert?value=&from=&to= · /toolbox/utils/selector?signature= · /toolbox/utils/keccak?text= — stateless EVM utilities (EIP-55, unit conversion, 4-byte selectors + topic0, keccak256), 1 unit each; MCP tool evm_utils. POST /toolbox/utils/verify-signature (EIP-191 personal_sign: message + signature + optional expected address) and POST /toolbox/utils/verify-siwe (EIP-4361: exact signed message + signature — signature + expiry verified, domain/nonce policy is yours), 1 unit each; MCP tool verify_signature. Recovery only — no keys held.

## x402 — pay-per-use, no signup (for agents)

Machine customers can use the gateway WITHOUT an account, paying per
use on-chain. GET https://flexyield.io/x402 returns the measured
route menu (cheap = public supply · balanced = wholesale blend · fast =
premium slice — priced from OUR OWN instruments, not a supplier's card)
and the payment challenge. Settle on the stated network, then
POST /x402/redeem { tx_hash, tier } to receive a spendable credential;
call the gateway with header X-PAYMENT: <tx_hash> until units or the
window are used up. TESTNET ONLY for now — real-money settlement opens
after regulatory sign-off.

## How we count (weighted units)

Quotas and rate windows count weighted units, not raw calls:

- standard calls = 1 unit
- heavy calls = 2 units — the debug_* / trace_* family, eth_simulateV1,
  eth_getLogs over more than 128 blocks, and state reads deeper than 128
  blocks from the chain head
- data API calls = 10 units
- toolbox calls = 1 unit (tx status: 2 — computed per hash); served from
  community supply and heavily cached — deliberately the cheapest line on
  the meter
- served from our cache = 0 units — an identical request inside the
  published TTL, RPC and toolbox alike; the rate window still counts it

## Caching (what we cache, for how long)

Cache hits cost 0 units and carry the header X-FlexYield-Cache: hit.
Quota, per-key caps and per-service caps are never consumed by a hit;
rate windows count every request. Only deterministic answers, only for
an identical request inside the TTL — never eth_call, eth_getLogs,
balances, nonces or anything relative to "latest":

- chain constants (eth_chainId, net_version): 1 week
- head reads: eth_blockNumber (2 s), eth_gasPrice (2 s), getSlot (1 s)
- by-hash lookups (eth_getBlockByHash, eth_getTransactionByHash, eth_getTransactionReceipt): 1 week, only once the block is 64 blocks below the head
- toolbox gas oracle: 12 s
- toolbox transaction status: 5 s
- toolbox ens resolve: 5 min
- toolbox token prices: 30 s
- toolbox contract intelligence: 24 h
- toolbox evm utilities: computed every call (never cached)

This table is identical on EVERY tier, free included — same catalog,
same weights, same parameter caps, same doorways. Upgrading changes how
much you can use and which supply serves you, never how we count.

## Method catalog and parameter limits

FlexYield serves an explicit catalog of JSON-RPC methods.

- A method outside the catalog answers error -32601 (HTTP 404). The error
  carries data.contact — that is an invitation, not a wall: write to
  hello@flexyield.io with what you are building and we enable or tailor it,
  usually within a day.
- eth_getLogs ranges are capped at 1,000 blocks and eth_feeHistory at 1,024
  blocks; beyond that the answer is -32602 (HTTP 400). Paginate, or ask us
  for a tailored package.
- getProgramAccounts is not served today (every upstream we measured fences
  it); the same doorway applies.

## Pricing

- Free: free — 1,000,000 requests/month included · burst up to 100 requests per 15 minutes
- Builder: $12.00/month — No request counting, no overage — a steady 30 requests/second, around the clock (up to ~78M/month included)
- Pro: $99.00/month — 15,000,000 requests/month included · burst up to 6,000 requests/min
- Pro (yearly): $990.00/year — 15,000,000 requests/month included · burst up to 6,000 requests/min
- Enterprise: custom plans with dedicated capacity — hello@flexyield.io

Full pricing: https://flexyield.io/pricing

## MCP (for AI agents)

FlexYield exposes its capabilities as an MCP server at https://flexyield.io/mcp (HTTP+SSE transport). Public tools need no authentication; account tools authenticate with your API key as a bearer token in the Authorization header.

Tools:
- create_api_key: Create a new FlexYield API key for the authenticated account. Returns the plaintext token exactly once — store it securely, it cannot be retrieved again.
- set_key_budget: Set or clear the monthly request budget of one of the account's API keys. Pass monthly_request_cap: null (or 0) to remove the cap.
- set_key_services: Read or change which gateway services ONE of the account's API keys may use (rpc, data, gas, tx_status, ens, prices, contracts, utils) and its per-service monthly unit caps. `enabled` = the FULL list to keep on for that key (others answer -32012 with blocked_by: key); `caps` = unit caps by service for that key alone (-32014 with scope: key once reached; an empty value clears). A key can never exceed the account's own service settings. No arguments besides id = read.
- claim_agent_start: Start claiming an existing agent by its EVM address: returns the exact SIWE message the agent's wallet must sign. Complete with claim_agent_complete.
- claim_agent_complete: Complete an agent claim: verify the wallet signature over the message from claim_agent_start and equip the agent with a budgeted API key (default budget 50000 requests/month). Returns the key exactly once.
- list_agents: List the account's claimed agents: name, address, proof, key id/prefix, budget and the services switched off for the key (set_key_services changes them).
- revoke_api_key: Revoke one of the authenticated account's API keys. Requests using the key stop working immediately. Idempotent.
- usage_report: Report the authenticated account's RPC gateway usage: total requests, success rate, latency (avg + p95), per-key volume/latency/errors/last-used, and per-method and per-chain counts.
- usage_volume: Requests over time for the authenticated account: zero-filled time buckets for a window (1h, 6h, 12h, 24h, 3d, 7d, 30d). Same data as the dashboard chart and CSV export; a bucket is marked partial when the window starts inside it or it is still filling.
- list_plans: List FlexYield's public subscription plans: prices in integer USD cents, billing interval, monthly included request quota, and burst rate limits. No authentication required.
- join_waitlist: Join the FlexYield early-access waitlist. Qualifier must be one of: developer, investor, curious. No authentication required.
- get_balances: Native balance (all supported chains) and ERC-20 token balances (chains with a data-capable upstream) for an address. Chains: e.g. eth_mainnet, base_mainnet, arbitrum_one, optimism_mainnet, polygon_pos, solana_mainnet.
- get_history: Recent asset transfers (sent + received, newest first) for an address on chains with a data-capable upstream. EVM chains only in v1.
- service_settings: Read or change the authenticated account's service settings: which gateway services (rpc, data, gas, tx_status, ens, prices, contracts, utils) are enabled and the optional monthly unit cap per service. No arguments = read. A capped service answers -32014 once month-to-date units reach the cap; a disabled one answers -32012.
- billing_status: Billing state of the authenticated account: current tier, whether payments are live, the subscription (plan, interval, price in USD cents, status, current period end, cancel-at-period-end), the card on file (brand, last4, expiry — never the number) and any founding-pricing reservation. Read-only; plan changes happen in the web console.
- usage_stats: Windowed statistics for the authenticated account, same data as the console's Statistics pages. report=latency: per-chain p50/p95 per bucket + summary. report=errors: 4xx/5xx by method and chain, per-bucket series and the most recent failures. report=spend: month-to-date pace (weighted units per day), projected month-end vs the plan's included volume and quota-exhaustion risk (no metered overage exists; Builder has no ceiling). report=cache: edge-cache hit rate, upstream calls avoided, measured time saved, units_saved (cache hits cost 0 units — the nominal weight they would have cost) and money_saved_cents at rate_basis (plan or pro_reference).
- set_notification_preferences: Set the account owner's notification preferences: usage alerts at 80% and 100% of the monthly quota, incident notices, and the console timezone (an ActiveSupport/IANA zone name).
- update_account_insights: Tell FlexYield about the account's setup (optional segmentation data): use case, team size, monthly volume, region, previous provider, referral source, chains in use, and chains you wish we supported. Allowed values: use_case trading_bots|indexing|wallet_dapp|analytics|other; team_size solo|2_5|6_20|20_plus; volume under_1m|1m_15m|15m_100m|100m_plus; region europe|north_america|asia_pacific|south_america|other; previous_provider alchemy|infura|quicknode|public_rpcs|self_hosted|first_setup; referral_source search|x_farcaster|friend|event|blog_newsletter|other; wish_chains avalanche|bnb|btc|ton|tron|sui|aptos|near|cosmos|other; chains = live chain slugs.
- enterprise_wishlist: Send FlexYield an enterprise wishlist: what would need to be true for you to run on FlexYield (chains, SLAs, compliance, features, prices; max 1000 chars) plus a contact email. The founders reply by email. No authentication required.
- get_gas_prices: EIP-1559 gas recommendations (slow/standard/fast: max fee + priority fee, wei and gwei) computed from FlexYield's multi-provider pool over the last 20 blocks. EVM chains only, e.g. eth_mainnet, base_mainnet, arbitrum_one, optimism_mainnet, polygon_pos.
- get_tx_status: Transaction status on any supported chain: confirmed/failed/pending/unknown, confirmations + gas (EVM) or slot + commitment (Solana). One call, any chain slug, e.g. eth_mainnet, base_mainnet, solana_mainnet.
- resolve_ens: ENS resolution on Ethereum mainnet: pass a name ('vitalik.eth') to get its address, or an address (0x…) to get its reverse-record name. On-chain via FlexYield's pool — reverse records are self-declared, forward-verify before trusting.
- get_token_prices: USD token prices read ON-CHAIN from Chainlink aggregator feeds through FlexYield's pool (no third-party price API). Supported symbols: eth, btc, link — more pairs on request. Each price carries updated_at and an honest stale flag.
- get_abi: Verified contract ABI (+ name, match level) from Sourcify's open dataset. Chains: eth_mainnet, base_mainnet, arbitrum_one, optimism_mainnet, polygon_pos. Unverified contracts return verified:false with the path to fix it.
- decode_calldata: Decode transaction calldata against the contract's verified ABI (Sourcify): function signature, selector, and argument values (static types decoded; dynamic types shown raw and labeled).
- evm_utils: EVM developer utilities: 'checksum' (EIP-55 checksum + validity for input=address), 'convert' (units wei…eth; input=value, from=unit, to=unit), 'selector' (4-byte selector + topic0 for input=function signature), 'keccak' (keccak256 of input text).
- verify_signature: Verify an EIP-191 personal_sign signature (mode 'personal': message + 65-byte 0x signature, optional expected address) or a SIWE/EIP-4361 message (mode 'siwe': the exact signed message text + signature — parses fields, checks signature and expiry; domain/nonce policy stays with you). Recovery only — FlexYield never holds keys.
- create_ticket: Open a support ticket for this account (or add to the open one with the same symptom). Quote the `request_id` from a failed call's error body and the exact call is attached automatically, with what usually fixes it. Returns the ticket reference (FY-…), status and the suggested path.
- list_tickets: List this account's support tickets (reference, subject, status, last activity). `status` filters; default = unresolved only.
- get_ticket: One ticket of this account in full: thread, what we found (evidence), suggested playbooks.
- reply_ticket: Add a message to one of this account's tickets, or mark it fixed (`resolve: true`) / reopen it.
- submit_feedback: Send product feedback for this account: a feature wish, a chain request, praise or a complaint. Private to the account; the answer and status show up in list_feedback.
- list_feedback: This account's feedback items with status and our reply.
- get_statement: This account's statement for a billing period (default: the current one): invoice facts plus usage grouped by API key / agent, chain and method class — requests, weighted units, cache hits, refusals. An agent's own key returns only that agent's usage. Periods follow the subscription cycle (or calendar months).
- list_statements: The account's billing periods (newest first) with their statement keys, for get_statement.

Resources:
- flexyield://plans: FlexYield subscription plans: prices in integer USD cents, billing interval, and rate limits.
- flexyield://getting-started: How to go from zero to a relayed JSON-RPC request on FlexYield.
- flexyield://reliability: Measured per-chain gateway reliability: uptime over 24h/7d/30d windows and latency percentiles (last 24h), from synthetic probes every 5 minutes.

## Pages

- Home: https://flexyield.io/
- Docs (API reference): https://flexyield.io/docs
- Integration guides (viem, ethers, web3.py, Solana web3.js, LangChain, CrewAI, OpenAI Agents SDK, MCP): https://flexyield.io/docs/guides
- Methods and limits (per-method weight, cache class, limit, doorway): https://flexyield.io/docs/methods
- Chain pages (measured uptime/latency, methods per dialect): https://flexyield.io/chains
- Pricing: https://flexyield.io/pricing
- Status (measured per-chain uptime and latency): https://flexyield.io/status
- Sign up: https://flexyield.io/registration/new

---

---
name: flexyield-gateway
description: >
  Use FlexYield as your blockchain access layer: one API key per agent with a
  monthly budget, JSON-RPC for 6 chains, a toolbox of
  higher-level tools (gas, ENS, prices, tx status), free response caching, and
  full account control over MCP. Card-billed by the key owner — no wallet needed.
license: Proprietary — see https://flexyield.io/terms
---

# FlexYield Gateway — Agent Skill

FlexYield is a unified access layer for blockchain infrastructure. You (an
agent) get a key, a budget, and measured routing; the human who runs you gets
one dashboard and one invoice.

## Authentication

Every call authenticates with an API key in the Authorization header:

    Authorization: Bearer fy_...

A human creates the account and the first key at https://flexyield.io (free
tier, no card required). Everything after that can be done by agents over MCP.

## JSON-RPC relay

    POST https://flexyield.io/rpc/{chain}
    Content-Type: application/json
    {"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}

Chains:
- `arbitrum_one`
- `base_mainnet`
- `eth_mainnet`
- `optimism_mainnet`
- `polygon_pos`
- `solana_mainnet`

Weighted metering: standard calls count 1 unit, heavy calls (traces, wide
getLogs) 2, data-API calls 10, toolbox calls 1 (tx status 2). **Cache hits
count 0** — repeated identical reads inside the freshness window are free.
Details: https://flexyield.io/docs#caching

## Toolbox (higher-level tools, one call instead of many)

    POST https://flexyield.io/toolbox/{service}

Services: gas (fee oracle), ens (resolve), prices (token prices), tx
(status/decode), abi (contract ABI), utils (EVM helpers). Same key, same
meter. Reference: https://flexyield.io/toolbox

## MCP — full account control for agents

    https://flexyield.io/mcp   (Authorization: Bearer <key>)

Tools include: `create_api_key(name, monthly_request_cap?)` ·
`set_key_budget(id, monthly_request_cap)` · `set_key_services(id, enabled[], caps{})` —
narrow one key to the services it may use and cap units per service for that key
(a fenced service answers -32012 with `blocked_by: key`, a capped one -32014 with
`scope: key`; a key is never wider than its account) · `revoke_api_key` ·
`usage_report(chain?, hours?)` — per-key volume, latency, errors, last-used ·
`billing_status` · `list_plans` · gas/ens/prices/tx/abi tools mirroring the
toolbox. Same meter, same fences on both doors: MCP data tools (gas, tx status,
balances, history) burn the same units and answer the same doorways as their
HTTP twins (-32005 rate, -32006 budget, -32007 quota, -32014 service cap);
management tools are rate-limited only.

## The fleet pattern (one owner, many agents)

**Already have an agent? Claim it.** An existing agent (any EVM wallet identity)
joins the fleet by proving ownership: `claim_agent_start(name, address)` returns
a standard sign-in message (EIP-4361); the agent's wallet signs it;
`claim_agent_complete(address, signature)` verifies and equips a budgeted key
(default 50000 requests/month) — shown once. `list_agents`
shows the fleet. Humans do the same on https://flexyield.io/agents with one
"Sign with wallet" click (the message is issued for the site you are on, so
the wallet shows no domain warning; no transaction, no gas).


1. The owner creates the account and one owner key.
2. For each agent, mint a key with a budget:
   `create_api_key(name: "agent-7", monthly_request_cap: 50000)`.
3. Each agent uses only its own key. Budgets are enforced per key on the hot
   path; an over-budget key gets a clear refusal with an upgrade doorway, and
   every other key keeps working.
4. `usage_report` shows spend per key; `set_key_budget` adjusts; `set_key_services`
   fences a key to e.g. gas + prices only (the robot may reach the charger, not the bank);
   `revoke_api_key` kills a leaked or retired key instantly.

Worked example: https://flexyield.io/docs · demo script in the repo
(`bin/demo/fleet_keys.rb`).

## Fair-use & doorways

Rate and plan limits answer with structured errors that say what to do next —
never a bare 429. If you need more than the fences allow, the response tells
you (or your human) exactly where the doorway is.

## When a call fails: file it, with the request_id

Every error body — HTTP and MCP — carries `data.request_id` and `data.support`
(`/support/new?request_id=…`). Over MCP: `create_ticket(subject, message,
request_id)` opens a ticket for the account; we attach that exact call, the
last 24 h of refusals, the key's caps and the chain status, plus the steps that
usually fix it. `get_ticket(reference)` shows the thread and the suggested path;
`reply_ticket(reference, message, resolve: true)` closes the loop when it is
fixed. The same symptom within an hour joins the open ticket instead of
opening a new one. Wishes and chain requests: `submit_feedback(kind, title,
chain?)` — private to the account, answered on the item (`list_feedback`).

## Your statement, without a dashboard

`list_statements` → the account's billing periods (its own subscription cycle, or
calendar months); `get_statement(period?)` → invoice facts plus usage grouped by
key and agent, by chain and method class: requests, weighted units, cache hits
(free), refusals. **A key that belongs to an agent gets that agent's usage only** —
every agent can read its own bill. Same over HTTP with the bearer key:
`GET https://flexyield.io/api/statements/<period>` (JSON) or `.csv`.

## Status & trust

- Live measured status: https://flexyield.io/status (public, per chain)
- Terms: https://flexyield.io/terms · Privacy: https://flexyield.io/privacy
- Machine summary of the whole site: https://flexyield.io/llms.txt