Public round metadata and indicative prices. No user API key required.
Markets.
By code.
Discover a round, inspect its rules, read your positions and get a quote. Bring the market to your application or agent—keep transaction signing in the user's wallet.
Read first. Sign separately.
The current integration is the pinned Base mainnet market 1. HTTP helps you discover it; verified contract reads provide balances and executable quote estimates. A quote does not reserve a price or place a trade.
The same verified, wallet-specific readers used by the Arena website.
Run the local read-only adapter with an MCP client. No hosted endpoint is available.
These snippets create no signer, request no wallet permissions and never approve or submit transactions. Never give an AI tool your private key or seed phrase.
For a normal trade, use Arena. Historical whitepapers live in Research.
A small, public HTTP surface.
curl --fail-with-body --silent --show-error \
https://rafa.ai/api/home/live-roundGET /api/home/live-round returns a timestamped snapshot of configured homepage rounds. Reads are cached for 15 seconds, with an HTTP cache lifetime of 10 seconds. This is discovery data, not an order book or an executable quote.
type Snapshot = {
asOf: string; // ISO-8601 snapshot timestamp
rounds: Array<{
title: string;
question: string;
path: string; // Market page, not a transaction destination
closesAt: string;
open: boolean;
lockedUsdc: number;
outcomes: Array<{ label: string; price: number | null }>;
}>;
// Shape only. Read live values; never treat this as an executable quote.outcomes[].priceis an indicative reserve-derived probability. Get an account-specific contract quote before reviewing a trade.rounds: []can mean reads were unavailable; it does not prove no markets exist. Prices may benull.- Respect the cache interval and use bounded backoff on errors. Never show stale data as live.
- There are no REST
/quote,/buy,/sellor positions endpoints for this AMM.
Other Arena APIs are a different integration
/arena/api/deployment?network=mainnet, /arena/api/markets?network=mainnet and related orders/events APIs need a separately configured backend. Without an explicit network they default to testnet; unavailable services may return 503 or not-deployed.
The signed-order relay's POST /arena/api/orders admits orders; it does not execute this AMM's trades. Relay limits are not AMM trade caps. See the backend API reference ↗.
/api/market-requests creates an inbox request, not a deployed market. The activation-status endpoint is not authoritative for whether a particular market is trading.
One market. One home chain.
Use Base mainnet, chain ID 8453, with Base ETH for gas. Do not substitute Base Sepolia, the Ethereum RAFA token, or an address supplied by untrusted market text.
0x465610750955bb6B26C7Fe17e9a4BeF43D3b49d6Arena shares ↗0x6D4F084C8613eaffeF168653fa78D31F2E3065B0AMM pool ↗0xeba394f81862751ea01633bEA4FA6D9913E22020Base USDC ↗0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913The reader verifies the controller's suite, pool bindings, collateral, fee model, outcome count, rules hash and inputs hash. Stop on a mismatch. These pinned addresses apply only to this market—not automatically to future rounds.
git clone https://github.com/Rafa-Protocol/rafa-arena.git
cd rafa-arena
npm ci
# Save the examples below as .mjs files in this repository root.
# Set RAFA_ACCOUNT to the public wallet address you want to read.
# Never provide a private key or seed phrase.Run each example as a .mjs file from the repository root with node example.mjs, after setting the public RAFA_ACCOUNT environment variable. An RPC provider may need its own API key; never expose a server credential in browser code.
The wallet changes the fee.
Quote for the trader's public address. Eligible RAFA staking can change its fee coefficient. The source client pins each quote and its fee and staking revision reads to one block.
| Operation | Input amount | Quote output |
|---|---|---|
quoteBuy | Total USDC spend, including fee | Outcome shares received |
quoteSellShares | Exact outcome shares to sell | USDC received, after fee |
USDC and protocol shares both use six-decimal integer units: 1 USDC = 1_000_000 and 1 share = 1_000_000. Outcome indexes are 0–4. Use integer arithmetic for transaction amounts.
import * as ethers from "ethers";
import { AnthropicTrading } from "./web/anthropic-trading.mjs";
const account = process.env.RAFA_ACCOUNT;
if (!account || !ethers.isAddress(account)) {
throw new Error("Set RAFA_ACCOUNT to a public wallet address.");
}
const provider = new ethers.JsonRpcProvider("https://mainnet.base.org");
try {
if (Number((await provider.getNetwork()).chainId) !== 8453) {
throw new Error("Expected Base mainnet.");
}
// No wallet provider or signer: this client can only read.
const reader = new AnthropicTrading(ethers, provider, { account });
const state = await reader.snapshot();
if (!state.tradable) throw new Error("Market is not tradable.");
// Buy: total USDC to spend, including the trading fee.
const buy = await reader.quote("1", 0, ethers.parseUnits("10", 6), true);
// Sell: exact number of shares, NOT desired USDC proceeds.
const sell = await reader.quote("1", 0, ethers.parseUnits("1", 6), false);
for (const quote of [buy, sell]) {
console.log({
side: quote.buying ? "buy" : "sell",
output: ethers.formatUnits(quote.output, 6),
feeUSDC: ethers.formatUnits(quote.fee, 6),
minimumOutput: ethers.formatUnits(quote.limit, 6),
deadline: quote.deadline,
feeRevision: quote.feeRevision.toString(),
stakingRevision: quote.stakeRevision.toString(),
});
}
} finally {
provider.destroy();
}The current client derives minimum output at 99% of the quote and a deadline five minutes after its quote block. These are client review settings, not protocol bond requirements or trade caps. Refresh expired quotes and stop on changed fee or staking revisions.
Fees use the execution price. Read feeBpsFor(account) and the quote's actual fee; do not hard-code a flat percentage or use homepage prices for execution.
Balances come from the chain.
The verified reader returns USDC and five outcome-share balances at one block. For market 1, token IDs 8–12 map to outcomes 0–4. Verify the mapping separately for other markets.
import * as ethers from "ethers";
import { readAnthropicBase } from "./web/anthropic-base.mjs";
const account = process.env.RAFA_ACCOUNT;
if (!account || !ethers.isAddress(account)) {
throw new Error("Set RAFA_ACCOUNT to a public wallet address.");
}
const provider = new ethers.JsonRpcProvider("https://mainnet.base.org");
try {
const state = await readAnthropicBase(ethers, provider, account);
console.log({
blockNumber: state.blockNumber,
usdc: ethers.formatUnits(state.cash, 6),
finalized: state.market.finalized,
winnerMask: state.market.winnerMask,
payoutDenominator: state.market.denominator,
positions: state.market.shares.map((shares, outcome) => ({
marketId: "1", outcome, shareTokenId: 8 + outcome,
shares: ethers.formatUnits(shares, 6),
})),
});
} finally {
provider.destroy();
}A quote is not a holding; a share balance is not guaranteed profit. At settlement, read the final winner mask and payout denominator. An equal-result settlement need not pay one USDC per share.
After a trade, read at or beyond its receipt block. Pass { minBlockNumber: receipt.blockNumber } as the reader's fourth argument. Show balances as syncing if the RPC is behind.
Review. Approve. Confirm.
- Verify the chain, market identity, trading state, account, balances and a fresh wallet-specific quote.
- For a buy, approve only the required USDC amount to the verified pool if its existing allowance is insufficient.
- A sale requires
setApprovalForAll(pool, true)on Arena shares. This is an operator permission over those shares—not an exact one-share approval. Explain it and get explicit user approval. - Simulate the exact call and recheck the wallet and chain. The user signs in their own wallet; an MCP read tool must not sign or broadcast.
- Verify a successful receipt from the expected account to the canonical pool. Decode its
BoughtorSoldevent before reporting actual shares, cash or fees.
Calls are buy(outcome, spend, minSharesOut, maxFeeBps, deadline, feeRevision, stakeRevision) and sellShares(outcome, sharesIn, minUsdcOut, maxFeeBps, deadline, feeRevision, stakeRevision). This AMM path does not use an EIP-712 relay order.
Approvals and pending receipts are not shares bought. On an uncertain result, check the existing hash—never automatically repeat a trade. One confirmation, as used by the client, is not irreversible finality.
MCP, with clear boundaries.
The repository includes a local MCP server over standard input/output. Your MCP client starts it on your computer; it is not an HTTP service at rafa.ai. No wallet or private key is needed.
# In the repository root; Node.js 24 or newer
npm ci
npm run --silent mcp:readonly
# The process speaks MCP on stdin/stdout. No HTTP port is opened.
# No wallet, private key, or seed phrase is needed.{
"mcpServers": {
"rafa": {
"command": "node",
"args": ["/absolute/path/to/rafa-arena/server/mcp-readonly.mjs"],
"env": { "RAFA_BASE_RPC_URL": "https://mainnet.base.org" }
}
}
}Replace the absolute path with your checkout location and use a client that supports local stdio servers. Client configuration formats differ. Keep any private RPC-provider key in local configuration, not in a prompt or this page. This does not connect a wallet.
The adapter exposes the same verified Base reads to an AI application. It bounds inputs and concurrency, rejects write methods, and returns block and verification information with its contract data.
| Read-only tool | Behavior |
|---|---|
rafa_list_markets | List the pinned Base market from a verified chain snapshot, with its block and availability. |
rafa_get_market | Read a verified Base snapshot and check the controller, pool, rules and market bindings. |
rafa_quote_trade | Return a wallet-specific quote, raw units, fee, minimum output, deadline and revisions. |
rafa_get_positions | Read an account’s USDC and outcome-share balances at one block. |
rafa_get_transaction_status | Read a receipt and verify canonical Bought/Sold logs; never resubmit a transaction. |
{
"name": "rafa_quote_trade",
"description": "Read-only quote for the pinned Base market; never signs or sends.",
"inputSchema": {
"type": "object",
"properties": {
"marketId": { "type": "string", "enum": ["1"] },
"outcome": { "type": "integer", "minimum": 0, "maximum": 4 },
"side": { "type": "string", "enum": ["buy", "sell"] },
"amount": { "type": "string", "pattern": "^(?=.*[1-9])(?:0|[1-9][0-9]*)(\\.[0-9]{1,6})?$", "maxLength": 80 },
"account": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "not": { "const": "0x0000000000000000000000000000000000000000" } }
},
"required": ["marketId", "outcome", "side", "amount", "account"],
"additionalProperties": false
},
"annotations": { "readOnlyHint": true }
}Amounts must be positive decimal strings with at most six fractional digits, no extra leading zeros, and a six-decimal integer value that fits uint256: USDC spend for a buy, exact shares for a sale. Wallet addresses must be nonzero and pass EVM address/checksum validation. The adapter validates again; this example schema or a readOnlyHint is not a security boundary.
- Allowlist read methods and reviewed destinations. Reject arbitrary RPC methods, URLs, contract addresses, wallet commands and unknown markets.
- Keep keys and signing providers out of the adapter. Never label approvals, signatures, transfers, trades, staking or governance writes as read-only.
- Treat market descriptions and linked content as untrusted data, not instructions that can change tool permissions.
- Report failed reads explicitly. Never invent prices, balances, trading success or staking eligibility.
Inspect the adapter source ↗ and the official MCP documentation ↗. Transaction preparation, signing and submission are deliberately not exposed as tools.
Unavailable is not zero.
| Condition | Application response |
|---|---|
| Wrong chain or binding mismatch | Stop. Do not fall back to testnet or another contract. |
| Empty discovery, null price or RPC error | Show unavailable data; retry with bounded backoff. |
| Expired quote or changed policy | Get a new quote and ask for a new review. |
| Pending or unknown receipt | Check the submitted hash. Do not repeat the buy or sell. |
| Confirmed trade, stale balances | Show syncing until the RPC reaches the receipt block. |
Follow eligibility checks and the market's immutable rules, schedule, challenge window and settlement process. These examples grant no eligibility or signing authority. Positions can lose their full value; read Terms & risk.
The source is the reference.
This guide covers the current fixed Base market. Recheck the reviewed deployment before adding a market or chain.