10. API Specification

10.1 Verification API

The Baseline API exposes RESTful endpoints for claim submission, Verification Object retrieval, attestation queries, and engine management.

Base URL: https://api.baseline.io/v1

10.2 Product API (Memecoin Intel Portal)

10.3 Authentication

The API supports three authentication mechanisms:

API Key (Server-to-Server)

For server-to-server integration.

Header: X-API-Key: <api_key>

OAuth 2.0 (End-User)

Providers: Google, Apple Flow: Authorization code with PKCE

Wallet Authentication (Web3)

Flow: Challenge-response with message signing

Session Management

JWT Configuration:

• Access token expiry: 15 minutes (configurable)
• Refresh token expiry: 7 days (configurable)
• Signing algorithm: HS256

10.4 Real-Time Data Pipeline

For real-time monitoring and low-latency alerts, the system provides:

WebSocket Endpoints:

Event Types (Server → Client):

{ "type": "event",       "data": "TradeEvent" }
{ "type": "ml_score",    "data": "MLScore" }
{ "type": "token_meta",  "data": "TokenMetadata" }
{ "type": "stats",       "data": "GlobalStats" }
{ "type": "feed_update", "data": "BaselineFeedItem" }

Supported DEX Sources (Solana):

Data Collection Method:

• Pure WebSocket subscription to on-chain logs (zero HTTP rate limiting)
• Events parsed directly from transaction logs (no getParsedTransaction calls)
• AES-256-GCM encrypted logging for compliance and ML training data
• Signature deduplication to prevent double-counting

10.5 SDK Type Contract (@baseline/core)

The Verification API endpoints above accept and return structured objects whose types are formally defined in Appendix F: SDK Type Definitions. Integrators building on Baseline SHOULD use a typed SDK client rather than constructing raw REST calls.

The @baseline/core package (reference implementation: TypeScript) exports:

Pagination contract: All list endpoints use cursor-based pagination. Clients pass { cursor?, limit? } as query parameters and receive { data: T[], pagination: { cursor, hasMore, total? } }. Cursors are opaque strings — clients MUST NOT parse or construct them.

Error contract: All errors return HTTP 4xx/5xx with a BaselineError body. The error.code field is a machine-readable discriminant (e.g., INVALID_CLAIM, VO_NOT_FOUND). Claim validation errors include a violations array with per-field details (JSONPath, rule, message).

See Appendix F for the complete type definitions, client interface, and usage examples.

10.6 Trust Advisory and Anchoring Status

Every VO response MUST include the baselineChain object with anchoringStatus and anchoringPhase fields. These fields are the consumer's primary signal for determining what level of independent verification is possible for a given VO.

Anchoring status values:

Migration phase context:

The anchoringPhase field (SHADOW, TESTNET, MAINNET, or null) indicates which migration phase (Section 8.8) the protocol was in when the VO was created. During SHADOW and TESTNET phases, all VOs have anchoringStatus: "PRE_ANCHORING" — consumers are trusting the operator with no on-chain recourse. Products built on Baseline during these phases SHOULD display this trust level prominently (e.g., "Operator-verified only — not yet anchored on-chain").

Recommended consumer behavior:

if (vo.baselineChain.anchoringStatus === "PRE_ANCHORING") {
  // Display: "Operator-verified — independent verification not yet available"
  // Do NOT present as independently verified
} else if (vo.baselineChain.anchoringStatus === "ANCHORED") {
  // Display: "Anchored on FirmaChain — independently verifiable"
  // Optionally verify: fetch Merkle proof, confirm against on-chain root
} else {
  // PENDING or FAILED — anchoring in progress
  // Display: "Verification pending on-chain confirmation"
}