B//T[ CONSOLE ↗ ][ MARKETS ↗ ][ SUPPORT ↗ ]
DEVELOPER ACCESS / V1

Build with Beggy.

Market data for your page.
Verified calls for your bot.

REFERENCE · 09 NOV 2026 · ALL TIMES UTC

01 / Start here

Read markets. Put them on your page. Prepare calls from your own wallet.

The public API needs no API key. Beggy returns market data and unsigned call instructions. Your integration owns signing, submission and recovery; the API does not custody funds or relay transactions.

NETWORKRobinhood Chain · 4663
SETTLEMENTUSDG · 6 decimals
GASETH on Robinhood Chain

Base URL

https://api.beggyterminal.xyz

USDG contract

0x5fc5360d0400a0fd4f2af552add042d716f1d168

[ OPEN CONSOLE ↗ ] [ VIEW MARKET JSON ↗ ]

Start with reading data. A live call stakes real USDG and requires gas. Use the same wallet for approval, simulation and entry. An approval for one pool or wallet does not cover another.

02 / Market endpoints

GET /v1/markets
Returns { version, feed, total, offset, limit, markets }.
GET /v1/markets/{marketId}
Returns { version, feed, market }. Use the market’s 32-byte ID, not its pool address.
curl "https://api.beggyterminal.xyz/v1/markets?type=RAID&status=LIVE&limit=20&offset=0"
QueryAccepted values
typeCOOK, RAID, HOLD · optional
statusLIVE, LOCKED, SCHEDULED, SETTLING, RESOLVED, CANCELLED, FINALIZED, UNKNOWN · optional
limit1–100 · default 50
offset0–999999 · default 0

Filters are case-sensitive. Unknown or repeated query parameters are rejected. Pagination uses offsets; save the ID of a selected market rather than relying on list order.

03 / Understand the data

FieldMeaning
id / poolAddressMarket identifier / entry contract address. They are different.
signedQuestionOriginal signed market wording. Do not reinterpret the settlement condition.
asset / type / statusLegacy single-asset metadata; contract family COOK, RAID or HOLD; reported market phase. Preserved for compatibility.
recipe / assets / displayRecipe kind, label, version and recognized flag; ordered asset identities with roles and exact rational weights; recipe title, duration label and introduction.
durationSeconds / source / rulesMarket duration; provider, quote currency and sampling policy; signed winning condition, comparator, tie/failure rules, event and halftime timestamps, and exact numeric parameters.
timesopensAt, entryClosesAt, closesAt: Unix seconds or null. timezone is UTC. These are not a complete event or settlement schedule; read the market rules.
settlementAsset / settlementTokenToken address; recognized USDG metadata includes decimals: 6.
limitsminimumBaseUnits / maximumBaseUnits as integer strings, or null if unavailable.
statsstakeBaseUnits, yesBaseUnits, noBaseUnits, players, calls, callsComplete, observedAt. Numeric amounts and counts are strings or null.
freshnessobservedAt, stale, classification and ageSeconds describe lifecycle data. Stats have their own observedAt.
feedretrievedAt is journal retrieval time; degraded indicates an upstream fallback.
urlDirect public market page with rules and entry UI.

Pool is stake only, excluding bonuses. YES/NO percentages represent stake share, not player voting or a guaranteed probability. Unknown counts must stay unknown; callsComplete: false means history is incomplete.

Confirmed reference and live quote observations, wallet lists and personal positions are not exposed. Exact signed target parameters are available in rules.parameters; these are not live observations. Use the linked market page for full terms.

Recipe metadata · added 9 November 2026

Use display.title as the main heading: ETF DUEL, DUEL, BASKET, PAIR, OUTSIDER, COMEBACK, PHOTO FINISH or PRICE TARGET. Keep type for legacy filters and routing. Use assets for all participants; the legacy asset field can be empty on multi-asset markets.

Asset roles identify FIRST/SECOND, CONSTITUENT, or CHALLENGER/BENCHMARK. Equal weights use exact fractions such as {numerator:1, denominator:3}. PAIR quote currency is source.unit. ETF margins use percentage points in rules.parameters.minimumOutperformancePp; they are not token prices.

rules.winningCondition preserves the signed question. Additional rule fields include comparator, tieOutcome, failurePolicy, referenceAt, observationAt, entryCutoffAt, halftimeAt and halftimeTiePolicy. Null means unavailable, never a default. Unknown recipes return recipe.recognized: false. Metadata recognition is not proof of a successful settlement test.

durationSeconds describes the market opening-to-close span. rules.observationDurationSeconds describes the reference-to-observation interval when known; event markets may have different spans. Exact parameters are for computation or explicitly labelled technical details. Round primary price displays without changing these values; never use preparation quotes as confirmed openings.

04 / Prepare an unsigned intent

POST /v1/markets/{marketId}/call-intent requires JSON with exactly these fields. Replace both placeholders before running.

curl -X POST "https://api.beggyterminal.xyz/v1/markets/MARKET_ID/call-intent"   -H 'Content-Type: application/json'   --data '{"wallet":"YOUR_PUBLIC_WALLET_ADDRESS","side":"YES","amountBaseUnits":"100000"}'

side is YES or NO. amountBaseUnits is a positive decimal integer string: 100000 = 0.10 USDG, 1000000 = 1.00 USDG. Never use floating-point multiplication for token amounts.

A successful response includes kind: UNSIGNED_CONTRACT_INTENT, chainId, from, to, value, ABI, functionName, args, settlementAsset and checksRequired. The function is enterMarket(uint8,uint256); YES maps to 1, NO to 2. Native value is zero; ETH still pays gas.

This endpoint rejects stale journal data with HTTP 409. It does not approve tokens, reserve a position or submit a call. Independently verify the expected pool and simulate against the current chain before signing.

05 / Wallet & bot workflow

  1. Select a market by ID. Inspect its rules, pool, network and cutoff.
  2. Use one wallet holding the intended USDG stake and sufficient ETH on chain 4663. Read the market’s current entry limits.
  3. Check USDG allowance for that exact pool. If insufficient, prepare an exact-amount approval and confirm it in your wallet. Wait for its receipt.
  4. Validate and simulate the entry with current contract state. Revalidate after any wallet, side, amount, market or network change.
  5. Review the prepared entry. Your wallet or your own bot signer submits it. Persist the hash and exact expected terms before retrying anything.
  6. Verify the receipt and matching entry event. Pending or unknown submission means check again, never send again automatically.

The console exposes these as APPROVE EXACT USDG AMOUNT → VERIFY + SIMULATE ONLY → VALIDATE CALL → SUBMIT REVIEWED CALL → CHECK RECEIPT. NEW CALL unlocks only after the previous receipt is confirmed or reverted.

Browser duplicate protection is local to that browser and origin. Bots must implement durable nonce, hash and retry tracking across processes and devices.

Read-only browser SDK example

Run inside your application after an explicit wallet-connect action. This example prepares a call; it does not sign or send it.

import { prepareLiveCall, verifyCallReceipt } from
  'https://api.beggyterminal.xyz/bot-client.mjs';

const base = 'https://api.beggyterminal.xyz';
const marketId = 'REPLACE_WITH_MARKET_ID';
const response = await fetch(`${base}/v1/markets/${marketId}`);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { market } = await response.json();
const provider = window.ethereum; // EIP-1193 provider
if (!provider) throw new Error('Wallet provider required');
const [wallet] = await provider.request({ method: 'eth_accounts' });
if (!wallet) throw new Error('Connect your wallet first');

const prepared = await prepareLiveCall({
  market, provider, wallet, side: 'YES', amountBaseUnits: '100000'
});
// Review prepared.transaction. Nothing has been sent.
// Your own explicit signing flow submits it and saves the hash.

// After submission, verify the saved hash and ORIGINAL terms:
// await verifyCallReceipt({ provider, hash: savedHash, expected: {
//   wallet, pool: market.poolAddress, side: 'YES', amount: '100000'
// }});

Server bots can adapt a provider exposing request({method, params}). verifyAndSimulate performs read-only checks without requiring an unlocked browser account; prepareLiveCall additionally requires the selected account from eth_accounts and checks ETH gas coverage. Keep signing credentials exclusively in your own signer, never in API requests or public pages.

SDK exports

prepareApproval({market, provider, wallet, amountBaseUnits})
Returns unsigned, exact-amount USDG approval data. Does not send it.
verifyAndSimulate({market, provider, wallet, side, amountBaseUnits})
Checks chain, fresh RPC head, lifecycle, entry window, limits, token, balance and allowance, then simulates and estimates gas. Contract restrictions remain authoritative.
prepareLiveCall({...same inputs, onStep?})
Adds connected-account and conservative ETH gas-budget checks. Returns transaction, verifiedAtBlock and maxGasCostWei.
verifyCallReceipt({provider, hash, expected})
Checks exact wallet, pool, calldata, amount, successful entry event and canonical receipt block. CONFIRMED requires at least two confirmations.

Legacy prepareLiveTest, verifyLiveTestReceipt and LIVE_TEST refer to the original fixed pilot. Use the general functions above for new integrations.

06 / Embed a market

Place this on your page and replace the market ID. No wallet connection is needed to display a card.

<script type="module"
  src="https://api.beggyterminal.xyz/widget.mjs"></script>
<beggy-market
  api-base="https://api.beggyterminal.xyz"
  market-id="REPLACE_WITH_MARKET_ID">
</beggy-market>

The card shows the recipe and assets, duration, introduction, signed question, source, status, pool, players, calls, YES/NO stake share and a link to the market. It refreshes every 60 seconds while visible and labels cached data. The console generates a ready-to-copy snippet for each selected market.

Cross-origin access is enabled. If your site uses a Content Security Policy, allow this origin for the module and API requests. Each visible card consumes read requests; account for the shared per-IP rate limit.

07 / Confirmation & feed delays

A confirmed entry and its appearance in the market board are separate steps. A verified matching contract receipt establishes the call; the public index may update later.

If a confirmed call is missing from the board, do not submit it again. Keep the transaction hash, pool, wallet and market ID for reconciliation. The API does not provide an index-repair endpoint.

Freshness classifications are CURRENT, DELAYED and HISTORICAL. HISTORICAL does not guarantee fresh claim accounting. Market lifecycle reads can be scheduled around deadlines, so old journal timestamps do not alone prove a failed RPC connection.

Normal in-process journal caching is 15 seconds. During upstream outages, last-good data may be returned for at most five minutes with feed.degraded: true; stale intents are blocked. The SDK’s independent live checks can evaluate current chain state even when the journal is delayed, but simulation is never a guarantee of execution.

08 / Errors & rate limits

Limits: 60 reads / 60 seconds and 10 intent requests / 60 seconds, aggregated per IP and domain. Netlify enforcement can lag; these are not precise synchronous counters. Back off on HTTP 429 and honor Retry-After when present.

Code / HTTPWhat to do
TOKEN_APPROVAL_REQUIRED · SDKApprove sufficient USDG for this wallet and this pool, wait for confirmation, then simulate again.
THIS_IS_TOKEN_APPROVAL_NOT_A_MARKET_CALL · SDKYou supplied an approval hash. Use the entry transaction hash.
INSUFFICIENT_TOKEN_BALANCE / INSUFFICIENT_ETH_FOR_GASFund the same wallet on Robinhood Chain with the missing asset.
WRONG_CHAIN / WALLET_CHANGEDReconnect the intended account on chain 4663 and revalidate.
MARKET_NOT_OPEN · 409 or SDKCheck the current entry window and contract status; do not reuse an earlier simulation.
MARKET_STATE_STALE · 409Wait for fresh journal data, or perform independent SDK live verification.
INVALID_* / AMOUNT_OUTSIDE_MARKET_LIMITS · 400Correct inputs. Use exact base-unit strings and valid full IDs/addresses.
MARKET_NOT_FOUND · 404Check the ID against the feed.
JSON_REQUIRED · 415 / BODY_TOO_LARGE · 413Send application/json with a body no larger than 2048 bytes.
RATE_LIMITED · 429Back off; do not retry in a tight loop.
MARKET_FEED_UNAVAILABLE · 503Retry later. Never interpret unavailable data as a zero position.

There is no public API for market publication, refunds, claims, webhooks or transaction relaying in this version. Claims remain in the market UI. Never bypass a wallet security warning to use an integration.

09 / Discord support

Need help with your integration or a call? Join our Discord support channel.

[ DISCORD SUPPORT ↗ ]

Include the market ID, transaction hash and error message. Never share a seed phrase or private key. If a transaction is pending or already confirmed, do not submit it again.