Back to home

Partner API

v1 35 Endpoints

Two API surfaces. HMAC-signed financial operations. Zero PII. Everything you need to embed prediction and conviction markets into your platform — external markets from the network, or internal markets created by your users.

OpenAPI 3.1

Full spec. Auto-generated client libraries.

SDKs

Python, Node.js, Go — official clients.

Sandbox

Full test environment. pk_test_* keys. No real money. Same API surface.

JSON responsesUUID identifiersIdempotent operationsWebhook retry with backoffHMAC request signingZero PII by design

Core Concepts

How it works

Three things to understand before you start integrating.

Two-Tier Auth

Two credentials. One API key (pk_*) identifies your partner account — used on every request. One signing secret (sk_*) authenticates financial operations via HMAC-SHA256.

Read ops (search, feed, prices) — API key only. Fast path.

Financial ops (join, withdraw, resale) — API key + HMAC signature + timestamp. Prevents replay and tampering.

pk_{env}_{partner}_{32B base62} sk_{env}_{partner}_{32B base62}

Header: X-AnyBid-Timestamp

Header: X-AnyBid-Signature

HMAC-SHA256(sk, timestamp + method + path + body)

Zero PII

Users are identified by opaque external_id only. We never store, process, or transmit personal data. Emails, names, phone numbers, and addresses are rejected at the validation layer — not filtered, rejected.

This is a hard architectural constraint, not a policy toggle. There is no admin override, no "just this once" field. Our database schema has no column for PII. Your compliance team will love us.

You own the user relationship. We own the market infrastructure. The external_id is the only bridge between the two — and it's opaque by design.

Format: ^[a-zA-Z0-9_-]{4,128}$

Coming Next

IP Whitelist — restrict API access to known server IPs. Extra layer on top of key auth.

gRPC — all AnyBid internal services already communicate via gRPC. We're extending this to the partner surface. Benefits: binary Protobuf (smaller payloads, faster serialization), bi-directional streaming, strongly typed contracts, HTTP/2 multiplexing.

REST isn't going anywhere — gRPC will be an additional option for partners who want lower latency and type safety.

Account Lifecycle

Six steps from zero to trading

Create an account, discover markets, fund the wallet, trade. That's the core loop.

1

Create Account

Partner calls POST /v1/accounts with an external_id. AnyBid returns account_id + deterministic wallet address.

2

Discover Markets

Semantic vector search, personalized feed, and deep learning recommendations. Our search embeds every market and matches user interests — your users see what's relevant to them, not a raw list.

3

Fund Wallet

Partner sends USDC on-chain to the wallet address. AnyBid detects deposits automatically.

4

Create or Join Markets

Create a new market from a natural language claim (quote → create flow), or join an existing one by picking a side and backing it with funds. Wallet balance checked, funds locked, matched peer-to-peer.

5

Market Resolves

Outcome determined by data sources. Winnings deposited to wallet automatically.

6

Withdraw

Partner requests withdrawal to any valid ERC20 address. USDC sent on-chain.

Integration Models

Two ways to integrate

Same API, same key, same endpoints. Choose the model that fits your team.

Model A: Headless API

Server-to-server contract. Your backend is the trust boundary. Build your own UI, your own UX, your own experience. Every endpoint in this doc is available to you.

Your frontend → Your backend → AnyBid API

Full control. Full flexibility.

Model C: Companion App

A white-labeled, pre-built prediction market UI deployed under your domain. Themed to your brand — colors, logo, radius, fonts. Open source, so you can inspect every line.

Your platform → Token redirect → Companion App → AnyBid API

Fastest path to production.

How the Companion App works

Architecture
  • SvelteKit frontend + thin proxy backend
  • Backend uses the same Headless API — no privileged access
  • Auth via one-time token redirect from your platform
  • Real-time updates via Server-Sent Events (webhook → SSE push)
Theming
  • Config-driven — one file per partner
  • Brand color, surface, text, radius, logo
  • Maps to CSS custom properties at runtime
  • No build step for rebranding — one config change, one deploy
partner.config.ts 
export const theme = {
  brand: '#FF6B00',
  surface: '#FFFFFF',
  text: '#1A1A1A',
  radius: '8px',
  logo: '/brand/logo.svg'
};

The companion app is open source. Without an API key, it's an empty shell — the value is in the infrastructure, not the UI code.

Group 1

Accounts

Create user accounts and wallets. Idempotent — same external_id returns the existing record.

POST /v1/accounts
API Key

Create account — returns account_id + wallet address

GET /v1/accounts/{account_id}
API Key

Get account info + wallet + balance

POST /v1/accounts/batch
API Key

Batch create accounts (migration)

Request — POST /v1/accounts 
{
  "external_id": "usr_abc123"
}
Response 200 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "usr_abc123",
  "wallet_address": "0x7a3b...f4e2",
  "balance_usdc": "0.00",
  "created": true
}
Response 400 — invalid external_id 
{
  "error": "invalid_external_id",
  "message": "external_id must be 4-128 characters, alphanumeric with _ and - only. No emails, no personal data."
}

Group 2

Markets (Discovery)

Search, browse, and get personalized recommendations. Non-financial — fast path, no ownership checks.

POST /v1/markets/search
API Key

Semantic vector search across markets

GET /v1/markets/{market_id}
API Key

Single market detail

POST /v1/markets/batch
API Key

Batch fetch markets by ID (max 50)

POST /v1/markets/{market_id}/prices
API Key

Lightweight price refresh

GET /v1/feed
API Key

Personalized recommendations (requires account_id)

POST /v1/accounts/{account_id}/onboard
API Key

Initialize interest profile

GET /v1/health
API Key

Service status

Group 3

Comments

Market discussion threads. Semi-anonymized. Cross-platform visibility. Intelligent backend does the heavy lifting.

GET /v1/markets/{market_id}/comments
API Key

Read comment thread

POST /v1/markets/{market_id}/comments
API Key

Post a comment

How comments work

  • Semi-anonymized — comments display partner-scoped display names, not real identities. Cross-platform by default: all partners see the same thread.
  • Position-aware ranking — comments from users with active positions (has_entry: true) are automatically ranked higher. No action required from partners — our backend links positions to comments and surfaces skin-in-the-game signal.
  • Embedding & intelligence — every comment is embedded by our backend. This powers intelligent relevance filtering, interest matching, and thread quality scoring.
  • Attachments — PNG/JPG, max 2 MB. Text limit: 1,000 characters.

Content filtering

  • Automated moderation — our backend filters pornographic, violent, and fraudulent content before it reaches any thread.
  • No external links — links are stripped. Prevents phishing, referral spam, and platform shilling.
  • Shill detection — users promoting external platforms or competing services are flagged and filtered automatically.
  • Report fee — flagging a comment costs $0.50 per report. This prevents spam flagging while keeping moderation accessible. Fee deducted from wallet.
Request — POST /v1/markets/{market_id}/comments 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "body": "BTC halving historically precedes 12-month bull runs. I'm betting yes.",
  "attachment_url": null
}
Response 200 
{
  "comment_id": "d58g7b04-fe6c-7e8d-c192-0gbf2e3d4a5c",
  "market_id": "f8590e95-5037-4564-8acb-43abed05c149",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "body": "BTC halving historically precedes 12-month bull runs. I'm betting yes.",
  "has_entry": true,
  "created_at": "2026-02-06T14:22:00Z"
}

Group 4

AI Reports

LLM-generated market analysis with real-time data from news and social APIs. GET is free once generated. POST triggers generation and deducts from wallet.

GET /v1/markets/{market_id}/report
API Key

Fetch generated report (free)

POST /v1/markets/{market_id}/report
Signed

Generate AI report (paid, deducts from wallet)

POST deducts the report fee from the requesting account's wallet. Once generated, GET returns the cached report at no cost. Fires report.generated webhook on completion.

Response — GET /v1/markets/{market_id}/report 
{
  "report_id": "rpt_2026_abc123",
  "market_id": "f8590e95-5037-4564-8acb-43abed05c149",
  "status": "completed",
  "generated_at": "2026-02-06T12:30:00Z",
  "summary": "Based on historical halving cycles and current macro conditions...",
  "confidence_score": 0.72,
  "data_sources": ["coingecko", "glassnode", "fed_funds_rate"],
  "sections": ["price_history", "on_chain_metrics", "macro_environment"]
}

Group 5

Market Creation

Two-step process: generate a quote, then create the market. Quote locks all parameters — tamper-proof.

POST /v1/quotes
API Key

Generate settlement quote for a claim

GET /v1/quotes/{quote_id}
API Key

Check quote status

POST /v1/markets/create/{quote_id}
Signed

Create market from approved quote

Step 1: Generate Quote

Request — POST /v1/quotes 
{
  "statement": "Bitcoin will exceed $150,000 by December 31, 2026",
  "settlement_date": "2027-01-01T00:00:00Z"
}
Response 200 
{
  "quote_id": "quo_2026_abc123_def456",
  "settleable": true,
  "tier": "AAA",
  "market_class": "HIGH_LOW",
  "fee": { "amount": "0.50", "currency": "USD" },
  "expires_at": "2026-02-06T12:15:00Z",
  "parsed_claim": {
    "subject": "Bitcoin price",
    "predicate": "above",
    "threshold": 150000,
    "threshold_unit": "USD"
  },
  "data_coverage": {
    "total_endpoints": 5,
    "unique_providers": 3,
    "coverage_level": "excellent"
  }
}

Step 2: Create Market

Request — POST /v1/markets/create/{quote_id} 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "fee_percent": 2.5
}
Response 200 
{
  "market_id": "f8590e95-5037-4564-8acb-43abed05c149",
  "status": "active",
  "quote_id": "quo_2026_abc123_def456",
  "fee_percent": 2.5,
  "title": "Bitcoin will exceed $150,000 by December 31, 2026",
  "outcome_a": "Yes",
  "outcome_b": "No",
  "deadline": "2027-01-01T00:00:00Z"
}

Settlability Tiers

Every claim is evaluated for settlability. The tier determines data coverage quality and the creation fee. Tiers are deterministic — same claim, same data sources, same tier. No surprises.

TierData CoverageIndicative Fee
AAAExcellent — multiple redundant data sources, high confidence~$0.02
AAStrong — reliable primary source with backup~$0.10
AGood — single reliable source~$0.50
BBBAdequate — data available but coverage gaps~$1.00
BBLimited — fewer sources, manual review possible~$2.00
BMinimal — best-effort resolution~$4.00

Fee philosophy: Fees are deterministic — they reflect the actual cost of aggregating and monitoring data endpoints for settlement. Our goal is to cover infrastructure costs, not to profit from market creation. Exact values may adjust between seasons as we refine data source agreements, but the tier a claim receives is always predictable and reproducible.

Group 6

Join Market

The money action. User picks a side and backs it with funds from their wallet.

POST /v1/markets/{market_id}/join
Signed

Join a market (side + amount)

GET /v1/accounts/{account_id}/entries
API Key

List markets account has joined

GET /v1/accounts/{account_id}/entries/{entry_id}
API Key

Single entry detail

Request — POST /v1/markets/{market_id}/join 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "side": "yes",
  "amount_usdc": "50.00"
}
Response 200 
{
  "entry_id": "a29f4e71-8c3d-4b5a-9e6f-7d8c9b0a1e2f",
  "market_id": "f8590e95-5037-4564-8acb-43abed05c149",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "side": "yes",
  "amount_usdc": "50.00",
  "odds_at_entry": 0.65,
  "potential_payout": "76.92",
  "fee_charged": "1.25",
  "status": "open"
}

Status lifecycle: open → matched → won | lost

Response 400 — insufficient balance 
{
  "error": "insufficient_balance",
  "available_usdc": "25.00",
  "required_usdc": "51.25",
  "breakdown": {
    "amount": "50.00",
    "fee": "1.25"
  }
}

Group 7

Resale

Selling a betting slip. Not trading. Conviction-compatible exit.

POST /v1/resale
Signed

List an entry for resale

DELETE /v1/resale/{listing_id}
Signed

Cancel a listing

POST /v1/resale/{listing_id}/buy
Signed

Buy someone's listed entry

GET /v1/markets/{market_id}/resale
API Key

Browse available listings for a market

Request — POST /v1/resale 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "entry_id": "a29f4e71-8c3d-4b5a-9e6f-7d8c9b0a1e2f",
  "ask_price_usdc": "55.00",
  "resale_target": "marketplace"
}
Response 200 
{
  "listing_id": "b38e5f82-9d4e-5c6b-af70-8e9d0c1b2f3a",
  "entry_id": "a29f4e71-8c3d-4b5a-9e6f-7d8c9b0a1e2f",
  "ask_price_usdc": "55.00",
  "resale_target": "marketplace",
  "status": "listed",
  "expires_at": "2026-02-13T12:10:00Z"
}

Two targets: marketplace (another user buys at asking price) or matching_engine (sell back at current odds, guaranteed fill).

Group 8

Withdrawals

Financial action with its own lifecycle. Destination can be any valid ERC20 address.

POST /v1/withdrawals
Signed

Request withdrawal to any ERC20 address

GET /v1/withdrawals/{withdrawal_id}
API Key

Check withdrawal status

Request — POST /v1/withdrawals 
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_usdc": "100.00",
  "destination_address": "0xdef..."
}
Response 200 
{
  "withdrawal_id": "c47f6a93-ae5f-6d7c-b081-9fae1d2c3a4b",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "amount_usdc": "100.00",
  "settlement_fee": "0.03",
  "net_amount": "99.97",
  "estimated_completion_seconds": 300
}

Group 9

Webhooks

Partner-level event delivery. Register endpoints, receive signed events with exponential backoff retry.

POST /v1/webhooks
API Key

Register webhook endpoint

GET /v1/webhooks
API Key

List registered webhooks

DELETE /v1/webhooks/{webhook_id}
API Key

Remove webhook

POST /v1/webhooks/{webhook_id}/test
API Key

Send test event

Event Catalog — 19 Events

EventTriggerKey Fields
market.joinedJoin submitted to contractentry_id, market_id, account_id, side, amount
market.joined.matchedFully matched peer-to-peerentry_id, account_id, tx_hash
market.joined.failedMatch failedentry_id, account_id, reason
market.resolvedOutcome determinedmarket_id, outcome, resolution_source
market.settledPayouts executedmarket_id, proof_bundle_url
market.createdNew market on networkmarket_id, title
market.pausedPaused by AnyBidmarket_id, reason
market.resumedResumed after pausemarket_id
market.voidedVoided + refunds issuedmarket_id, reason, refund_count
balance.updatedAny balance changeaccount_id, new_balance, change_amount, reason
withdrawal.completedWithdrawal on-chainwithdrawal_id, account_id, tx_hash
resale.listedEntry listed for resalelisting_id, entry_id, account_id, ask_price
resale.soldResale executedlisting_id, buyer_account_id, seller_account_id, price
resale.cancelledListing cancelled/expiredlisting_id, reason
report.generatedAI report completedreport_id, market_id, account_id
comment.deletedComment soft-deletedcomment_id, market_id, account_id
comment.flaggedFlagged by another partnercomment_id, flagged_by_partner
account.warnedModeration warning issuedaccount_id, reason
account.suspendedAccount suspendedaccount_id, reason, suspended_until

Delivery Envelope

Signed with X-AnyBid-Signature (HMAC-SHA256). Retry: 30s → 2min → 10min → 1hr → 6hr. Dead letter after 5 failures. Expected: 2xx within 5 seconds.

Webhook Delivery Example 
{
  "event": "market.joined.matched",
  "event_id": "e69b8cb5-ca7b-8f9e-d2a3-b1ca3f4e5c6d",
  "timestamp": "2026-02-06T12:10:05Z",
  "data": {
    "entry_id": "a29f4e71-8c3d-4b5a-9e6f-7d8c9b0a1e2f",
    "market_id": "f8590e95-5037-4564-8acb-43abed05c149",
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "side": "yes",
    "amount_usdc": "50.00",
    "odds_at_entry": 0.65,
    "tx_hash": "0xabc..."
  }
}

Group 10

Tracking

Batch behavioral events. Fire-and-forget, processed async. Zero extra round trips with piggyback.

POST /v1/tracking/events
API Key

Batch behavioral events (fire-and-forget)

How _piggyback works

Every API request you're already making can carry tracking data as a free rider — no extra HTTP call needed.

  • POST requests — add a _piggyback field to the JSON body. It's stripped before processing and forwarded to the tracking pipeline.
  • GET requests — set the X-Piggyback header with base64-encoded JSON. Same pipeline, no body required.
  • Batch endpoint — for high-volume events or when you want to flush a buffer, use POST /v1/tracking/events directly.
Piggyback on a POST request 
{
  "account_id": "550e8400-...",
  "side": "yes",
  "amount_usdc": "50.00",
  "_piggyback": {
    "events": [
      { "type": "page_view", "page": "/market/btc-150k" },
      { "type": "click", "target": "join_button" }
    ]
  }
}
Piggyback on a GET request 
GET /v1/markets/f859...
X-Piggyback: eyJ0eXBlIjoicGFnZV92aWV3In0=
// base64 of {"type":"page_view"}

Lightweight JS SDK

Coming soon

A tiny client-side SDK (~2 KB) that buffers tracking events and automatically attaches them as _piggyback payloads on your next API call. Drop-in for any frontend — no separate tracking endpoint, no extra requests. Just anybid.track('page_view', { page: '/market/btc' }) and it rides along on whatever API call fires next.

Partner Mod API

Comment Moderation

Moderate comments from your own users. Flag content from other partners' users for review.

Key principle: You have delete authority over your own users' comments. For comments by other partners' users, you can only flag — AnyBid reviews and acts.

DELETE /v1/mod/comments/{comment_id}
API Key

Delete own user's comment

POST /v1/mod/comments/{comment_id}/flag
API Key

Flag comment for review

GET /v1/mod/comments/flagged
API Key

List flags you've submitted

GET /v1/mod/comments/reported
API Key

Your users flagged by others

DELETE /v1/mod/comments/{comment_id} — 200 
{
  "comment_id": "d58g7b04-fe6c-7e8d-c192-0gbf2e3d4a5c",
  "status": "deleted"
}
DELETE /v1/mod/comments/{comment_id} — 403 
{
  "error": "not_your_user",
  "message": "Comment belongs to another partner's user. Use POST /flag instead."
}
POST /v1/mod/comments/{comment_id}/flag 
{
  "reason": "spam",
  "details": "Repeated promotional content"
}
Response 200 
{
  "flag_id": "flg_2026_xyz789",
  "comment_id": "d58g7b04-fe6c-7e8d-c192-0gbf2e3d4a5c",
  "status": "pending_review",
  "created_at": "2026-02-06T15:00:00Z"
}
GET /v1/mod/comments/flagged — Response 200 
{
  "flags": [
    {
      "flag_id": "flg_2026_xyz789",
      "comment_id": "d58g7b04-fe6c-7e8d-c192-0gbf2e3d4a5c",
      "reason": "spam",
      "status": "pending_review",
      "created_at": "2026-02-06T15:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

Complete Surface

35 Endpoints

Two API surfaces. Two auth levels. One API key.

Partner API — 31 Endpoints

GroupCountAuth LevelPriority
Accounts3API Key (create/read)P0
Markets (Discovery)7API Key onlyP0
Comments2API KeyP1
AI Reports2API Key + Signed on generateP1
Market Creation3Signed on create, API Key on quotesP0
Join Market3Signed on join, API Key on readP0
Resale4Signed on all write opsP1
Withdrawals2SignedP0
Webhooks4API Key (partner-level)P0
Tracking1API KeyP1
Subtotal31

Partner Mod API — 4 Endpoints

GroupCountAuth LevelPriority
Comment Moderation4API KeyP1
Subtotal4

Total: 35 endpoints across 2 API surfaces

Funding

What we do and don't do

Blockchain is the deposit mechanism. We watch the chain and update balances. You handle collection.

We do

  • ✓ Generate deterministic wallet address per account at creation
  • ✓ Watch on-chain for incoming USDC to known wallets
  • ✓ Update balance when deposits confirm
  • ✓ Fire balance.updated webhook
  • ✓ Reject joins when balance insufficient (with exact shortfall)
  • ✓ Process withdrawals to any valid ERC20 address

We don't

  • ✗ Collect money from users (partner's responsibility)
  • ✗ Convert fiat to USDC (partner's responsibility)
  • ✗ Provide deposit notification endpoint (the chain is the notification)
  • ✗ Care when or how the partner funds wallets
  • ✗ Restrict withdrawal destinations (valid address = we send it)

Developer Tooling

Everything you need to ship

Tools, specs, and environments to accelerate your integration.

Available Now

  • ✓ Full REST API with JSON responses
  • ✓ Sandbox environment (pk_test_* keys)
  • ✓ Webhook testing endpoint (POST /v1/webhooks/{id}/test)
  • ✓ Idempotent account creation
  • ✓ HMAC request signing for financial security

How We Build

We build what you actually need

Not what we think you need. Every feature on this page exists because a partner asked for it.

Partner-Driven Roadmap

We work closely with every partner. Our roadmap is shaped by your real integration challenges, not internal assumptions. Comments, AI Reports, the tier system, piggyback tracking — all built because partners told us they needed it.

We focus on core infrastructure — settlement, matching, data aggregation — and extend the surface based on what you actually hit in production.

Request a Feature

Missing something? Tell us. We love feedback because it means we're building the right thing. Every partner gets a direct line to the engineering team.

Feature requests go into a shared backlog, prioritized by partner demand. If multiple partners need it, it ships fast. If it's unique to your use case, we'll work with you on the design.

Ready to integrate?

One API key. Six weeks to production. Your brand, your users, your revenue.

Back to Home