{ "openapi": "3.1.0", "info": { "title": "SaTT public API", "version": "0.2.0", "summary": "Public API of SaTT — advertising pools (AdPools) where creators are paid for Oracle-verified social posts, in crypto or in dollars.", "description": "Base URL https://satt.com (same origin as the website). Two editions share this API:\n- **Crypto** — AdPools are smart contracts on BNB Chain; the public alpha runs on **BSC Testnet (chainId 97) with test SaTT**. Amounts are token base units (18 decimals) as decimal strings.\n- **Dollars (no-crypto)** — e-mail accounts with a USD balance (`/api/fiat/*`, integer cents). The alpha runs in **test mode**: free test funds, simulated payouts, no real money.\n\nRead endpoints are public. Wallet writes require a short-lived EIP-712 signature from the acting wallet; account endpoints use the `__session` cookie (plus an allowed `Origin` for writes). Admin and operator routes are intentionally not described here.\nErrors are JSON `{ error, ...details }` with a stable machine code. Requests are rate-limited per client IP (HTTP 429 with `Retry-After`).\n\nAI agents: a read-only Model Context Protocol server is available at `POST /api/mcp` (stateless Streamable HTTP, no auth). Docs for LLMs: https://satt.com/llms.txt and https://satt.com/llms-full.txt. API catalog (RFC 9727): https://satt.com/.well-known/api-catalog.", "contact": { "name": "SaTT", "url": "https://satt.com", "email": "contact@satt.com" } }, "servers": [ { "url": "https://satt.com" } ], "tags": [ { "name": "Platform", "description": "Service health, feature switches and configured providers." }, { "name": "AdPools", "description": "Crypto AdPools (BNB Chain): registry, live on-chain state, per-network prices, audience tiers, branding, participation stats and submissions." }, { "name": "Dollar edition", "description": "No-crypto AdPools paid in US dollars (integer cents). Alpha: test mode, free test funds, no real money." }, { "name": "Quests", "description": "Quest pools: actions → tickets → prizes with a draw anyone can recompute (frozen Merkle root + future BSC block hash). Verified accounts only." }, { "name": "Creators", "description": "Creator directory: listed SaTT accounts (`satt:`, \"Verified creator\" first) plus the imported crypto-creator directory. Public handles only; e-mails never leave the server." }, { "name": "Verification", "description": "Public proofs: Oracle-signed attestations, verified-account receipts, metrics sources and per-network tracking capabilities." }, { "name": "Receipts", "description": "Verified-account receipts: EIP-712 `VerifiedAccountReceipt` signed by the Oracle for each crypto payout, proving the post was on a social account verified on its network." }, { "name": "Market", "description": "SaTT token figures and a cached crypto market proxy." }, { "name": "Account", "description": "The signed-in satt.com account (`__session` cookie). Never returns tokens." }, { "name": "Analytics", "description": "\"My stats\" for the signed-in creator: per connected network, profile and recent post numbers." }, { "name": "AI agents", "description": "Model Context Protocol endpoint for AI agents." }, { "name": "Oracle network", "description": "Open oracle marketplace: identity proofs (OwnershipMatch), oracle registry and offers, measurement jobs, signed MetricsReports, quorum aggregates, oracle fees, self-signed creator claims (always verified). Guide: https://satt.com/oracles/become - docs/ORACLE-NETWORK.md." } ], "paths": { "/health": { "get": { "tags": ["Platform"], "summary": "Service health, version, git commit and chain connectivity", "responses": { "200": { "description": "Health report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getHealth", "security": [] } }, "/api/price/satt": { "get": { "tags": ["Market"], "summary": "SaTT/USD price from the PancakeSwap SaTT/WBNB pool (TWAP when available)", "responses": { "200": { "description": "Price quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SattPrice" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiPriceSatt", "security": [] } }, "/api/adpools": { "get": { "tags": ["AdPools"], "summary": "Paginated AdPools with on-chain state (empty list before launch)", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } } ], "responses": { "200": { "description": "AdPools page", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "configured": { "type": "boolean", "description": "false while no factory is deployed" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "description": "Paginated registry with live on-chain state, branding (`meta`) and per-network prices (`rates`). Page size capped at 50. Before a factory is deployed: `{ total: 0, campaigns: [], configured: false }`.", "operationId": "getApiAdpools", "security": [] } }, "/api/adpool/{id}": { "get": { "tags": ["AdPools"], "summary": "One AdPool: registry record plus live on-chain info", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "AdPool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "503": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolById", "security": [], "description": "Registry record + live on-chain info() + meta + reward + rates. uid=197609(Gauthier) gid=197121 groups=197121 is the registry index (0-based)." } }, "/api/creators": { "get": { "tags": ["Creators"], "summary": "Search the crypto creator directory", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Name, handle or country" }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "youtube", "twitter", "instagram", "tiktok", "facebook", "linkedin", "snapchat", "twitch" ] }, "description": "Use \"twitter\" for X" }, { "name": "niche", "in": "query", "schema": { "type": "string", "maxLength": 40 }, "description": "Topic, e.g. nft" }, { "name": "country", "in": "query", "schema": { "type": "string", "maxLength": 40 } }, { "name": "withEmail", "in": "query", "schema": { "type": "boolean" }, "description": "Only creators reachable by e-mail (addresses are never returned)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["reach", "name", "recent"], "default": "reach" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Creators page", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "creators": { "type": "array", "items": { "$ref": "#/components/schemas/Creator" } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "description": "Listed SaTT \"Verified creator\" accounts first (ids `satt:`), then the imported directory. 503 `directory_unimported` when neither is available.", "operationId": "getApiCreators", "security": [] } }, "/api/creators/facets": { "get": { "tags": ["Creators"], "summary": "Directory totals and facets (platforms, topics, countries)", "responses": { "200": { "description": "Facets", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiCreatorsFacets", "security": [] } }, "/api/creator/{id}": { "get": { "tags": ["Creators"], "summary": "One creator profile with linked social accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Creator", "content": { "application/json": { "schema": { "type": "object", "properties": { "creator": { "$ref": "#/components/schemas/Creator" } } } } } }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "description": "Directory id or `satt:` (a listed SaTT account: public handles, verification, participation). 503 `directory_unavailable` during an outage (never a false 404).", "operationId": "getApiCreatorById", "security": [] } }, "/api/attestations": { "get": { "tags": ["Verification"], "summary": "Public feed of Oracle-signed attestations (claims and metrics)", "parameters": [ { "name": "adpool", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "creator", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Attestations page", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAttestations", "security": [] } }, "/api/attestations/{id}": { "get": { "tags": ["Verification"], "summary": "One attestation with full EIP-712 typed data, signature and server-side verification", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verifiable attestation", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAttestationsById", "security": [] } }, "/api/metrics/sources": { "get": { "tags": ["Verification"], "summary": "Metrics sources the Oracle can use and whether each is configured", "responses": { "200": { "description": "Sources", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiMetricsSources", "security": [] } }, "/api/ai/status": { "get": { "tags": ["Platform"], "summary": "AI Studio availability, model and credit pricing", "responses": { "200": { "description": "AI status", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAiStatus", "security": [] } }, "/api/crypto": { "get": { "tags": ["Market"], "summary": "Top cryptocurrencies by market cap (cached CoinGecko proxy)", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250 } } ], "responses": { "200": { "description": "Coins", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiCrypto", "security": [] } }, "/api/crypto/{id}": { "get": { "tags": ["Market"], "summary": "One coin's detail (CoinGecko id, e.g. bitcoin)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coin", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiCryptoById", "security": [] } }, "/api/crypto/{id}/chart": { "get": { "tags": ["Market"], "summary": "Price history", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "string", "enum": ["1", "7", "30", "365", "max"] } } ], "responses": { "200": { "description": "Chart points", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiCryptoByIdChart", "security": [] } }, "/api/mcp": { "post": { "tags": ["AI agents"], "summary": "Model Context Protocol endpoint (Streamable HTTP, stateless, read-only)", "description": "JSON-RPC 2.0 MCP messages (initialize, tools/list, tools/call, resources/read). Send `Accept: application/json, text/event-stream`. Tools: get_platform_info, get_satt_price, list_adpools, get_adpool, search_creators, get_creator, get_directory_stats, list_attestations, verify_attestation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiMcp", "security": [] } }, "/api/oracle-network/v1": { "get": { "tags": ["Oracle network"], "summary": "Network description: EIP-712 domain, identity and payout signers, quorum, typed-data definitions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1", "security": [] } }, "/api/oracle-network/v1/stats": { "get": { "tags": ["Oracle network"], "summary": "Live counters: oracles, reports in 24 h, jobs, self-reports, receipts issued, networks covered", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1Stats", "security": [] } }, "/api/oracle-network/v1/oracles": { "get": { "tags": ["Oracle network"], "summary": "Oracle directory (SaTT Oracle first): status, platforms, reputation stats, current offer", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "approved", "suspended"] } }, { "name": "platform", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["price", "reputation"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1Oracles", "security": [] } }, "/api/oracle-network/v1/oracles/{address}": { "get": { "tags": ["Oracle network"], "summary": "One oracle and its signed registration", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Oracle", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1OraclesByAddress", "security": [] } }, "/api/oracle-network/v1/oracles/{address}/offers": { "get": { "tags": ["Oracle network"], "summary": "Every signed offer version of an oracle", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1OraclesByAddressOffers", "security": [] } }, "/api/oracle-network/v1/oracles/{address}/earnings": { "get": { "tags": ["Oracle network"], "summary": "Oracle fee ledger: summary per pool and currency, entries, claims", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1OraclesByAddressEarnings", "security": [] } }, "/api/oracle-network/v1/register": { "post": { "tags": ["Oracle network"], "summary": "Register or update an oracle (signed OracleRegistration; pending until approved)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["registration", "signature"], "properties": { "registration": { "$ref": "#/components/schemas/OracleRegistration" }, "signature": { "$ref": "#/components/schemas/Signature" } } } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Register", "security": [] } }, "/api/oracle-network/v1/offers": { "post": { "tags": ["Oracle network"], "summary": "Publish a signed, versioned OracleOffer (applies to jobs created afterwards)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["offer", "signature"], "properties": { "offer": { "$ref": "#/components/schemas/OracleOffer" }, "signature": { "$ref": "#/components/schemas/Signature" } } } } } }, "responses": { "201": { "description": "Published", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Offers", "security": [] } }, "/api/oracle-network/v1/match": { "get": { "tags": ["Oracle network"], "summary": "Identity layer: signed OwnershipMatch of wallet, verified account and post link, or {matched:false, reason}", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "Match result", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1Match", "security": [] }, "post": { "tags": ["Oracle network"], "summary": "Batch ownership matches (at most 25)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 25, "items": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Address" }, "url": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Match", "security": [] } }, "/api/oracle-network/v1/jobs": { "get": { "tags": ["Oracle network"], "summary": "Open measurement jobs for the calling oracle (signed headers, action \"jobs\")", "parameters": [ { "name": "x-satt-wallet", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "x-satt-deadline", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "x-satt-signature", "in": "header", "required": true, "description": "signature of OracleRequest{oracle, action, deadline}", "schema": { "$ref": "#/components/schemas/Signature" } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/OracleJob" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1Jobs", "security": [] } }, "/api/oracle-network/v1/feed": { "get": { "tags": ["Oracle network"], "summary": "Public list of jobs", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open", "final", "expired"] } }, { "name": "pool", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1Feed", "security": [] } }, "/api/oracle-network/v1/jobs/{id}": { "get": { "tags": ["Oracle network"], "summary": "One job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1JobsById", "security": [] } }, "/api/oracle-network/v1/jobs/{id}/reports": { "get": { "tags": ["Oracle network"], "summary": "Every signed report of a job and the aggregate (quorum, median, outliers)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reports", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1JobsByIdReports", "security": [] } }, "/api/oracle-network/v1/reports": { "post": { "tags": ["Oracle network"], "summary": "Submit a signed MetricsReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["report", "signature"], "properties": { "report": { "$ref": "#/components/schemas/MetricsReport" }, "signature": { "$ref": "#/components/schemas/Signature" } } } } } }, "responses": { "201": { "description": "Accepted (status, jobStatus, result)", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Reports", "security": [] } }, "/api/oracle-network/v1/estimate": { "post": { "tags": ["Oracle network"], "summary": "Pool plan before funding: coverage per network (SaTT / others / none), selected oracles, estimated oracle cost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["edition", "platforms"], "properties": { "edition": { "type": "string", "enum": ["crypto", "fiat"] }, "platforms": { "type": "array", "items": { "type": "string" } }, "expectedPosts": { "type": "number" }, "posts": { "type": "object", "additionalProperties": { "type": "number" } }, "measurementsPerPost": { "type": "number", "default": 4 }, "mode": { "type": "string", "enum": ["auto", "manual"] }, "oracles": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Estimate", "security": [] } }, "/api/oracle-network/v1/pools/{pool}/oracles": { "get": { "tags": ["Oracle network"], "summary": "Oracle configuration, plan and fees of a pool", "parameters": [ { "name": "pool", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platforms", "in": "query", "schema": { "type": "string" } }, { "name": "expectedPosts", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1PoolsByPoolOracles", "security": [] }, "post": { "tags": ["Oracle network"], "summary": "Set the pool oracle configuration (crypto: signed PoolOracleConfig by the on-chain manager; dollar: owner session)", "parameters": [ { "name": "pool", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1PoolsByPoolOracles", "security": [] } }, "/api/oracle-network/v1/claims": { "post": { "tags": ["Oracle network"], "summary": "Claim accrued oracle fees on a pool (signed headers, action \"claim\", single use)", "parameters": [ { "name": "x-satt-wallet", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "x-satt-deadline", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "x-satt-signature", "in": "header", "required": true, "description": "signature of OracleRequest{oracle, action, deadline}", "schema": { "$ref": "#/components/schemas/Signature" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pool": { "type": "string" } } } } } }, "responses": { "201": { "description": "Dollar credit or signed OracleClaim", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1Claims", "security": [] } }, "/api/oracle-network/v1/self-reports": { "get": { "tags": ["Oracle network"], "summary": "Public self-signed creator claims (status=pending: awaiting verification)", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "verified", "overclaimed"] } }, { "name": "pool", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1SelfReports", "security": [] }, "post": { "tags": ["Oracle network"], "summary": "Submit a self-signed claim (always verified before payment; paid on min(declared, verified))", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "report": { "$ref": "#/components/schemas/SelfReport" }, "signature": { "$ref": "#/components/schemas/Signature" } } }, { "type": "object", "description": "dollar edition (session cookie)", "properties": { "url": { "type": "string" }, "poolId": { "type": "string" }, "metrics": { "type": "object" }, "observedAt": { "type": "integer" }, "claimAmountCents": { "type": "integer" } } } ] } } } }, "responses": { "201": { "description": "Pending self-report", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1SelfReports", "security": [] } }, "/api/oracle-network/v1/self-reports/policy": { "get": { "tags": ["Oracle network"], "summary": "Self-report record of a creator: honest, offences, bond %, banned", "parameters": [ { "name": "wallet", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1SelfReportsPolicy", "security": [] } }, "/api/oracle-network/v1/self-reports/{id}": { "get": { "tags": ["Oracle network"], "summary": "One self-signed claim and its challenges", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Self-report", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleNetworkV1SelfReportsById", "security": [] } }, "/api/oracle-network/v1/self-reports/{id}/challenges": { "post": { "tags": ["Oracle network"], "summary": "Attach signed evidence to a self-report (never replaces verification)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["challenge", "signature"], "properties": { "challenge": { "$ref": "#/components/schemas/Challenge" }, "signature": { "$ref": "#/components/schemas/Signature" } } } } } }, "responses": { "201": { "description": "Recorded", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "$ref": "#/components/responses/Error" } }, "operationId": "postApiOracleNetworkV1SelfReportsByIdChallenges", "security": [] } }, "/api/satt/token": { "get": { "tags": ["Market"], "summary": "SaTT token figures", "description": "Price, liquidity, supply, burn and market cap (server-side, cached ~60 s).", "responses": { "200": { "description": "Token stats", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Token figures" } } } }, "503": { "$ref": "#/components/responses/Error" }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiSattToken", "security": [] } }, "/api/adpool/stats": { "get": { "tags": ["AdPools"], "summary": "Participation stats for several AdPools", "description": "Batched, cached 45 s. Invalid ids are ignored.", "parameters": [ { "name": "ids", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated AdPool addresses (≤ 100)" } ], "responses": { "200": { "description": "Stats by AdPool address", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AdpoolStats" } } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolStats", "security": [] } }, "/api/adpool/{adpool}/rates": { "get": { "tags": ["AdPools"], "summary": "An AdPool's per-network prices", "description": "Fixed reward per post (audience tiers) or performance prices (per 1,000 views / like / share). Nulls when unset. Amounts are gross token base units.", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Rates", "content": { "application/json": { "schema": { "type": "object", "properties": { "adpool": { "$ref": "#/components/schemas/Address" }, "mode": { "type": ["string", "null"], "enum": ["bounty", "performance", null] }, "rates": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/NetworkRate" } }, { "type": "null" } ] }, "maxPostsPerCreator": { "type": ["integer", "null"] }, "decimals": { "type": ["integer", "null"] } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolRates", "security": [] } }, "/api/adpool/{adpool}/tiers": { "get": { "tags": ["AdPools"], "summary": "Audience tiers with slots taken", "description": "Per network: each tier plus `taken` = distinct creators holding a live or redeemed attestation in it.", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Tiers", "content": { "application/json": { "schema": { "type": "object", "properties": { "adpool": { "$ref": "#/components/schemas/Address" }, "mode": { "type": ["string", "null"] }, "rates": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/NetworkRate" } }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolTiers", "security": [] } }, "/api/adpool/{adpool}/reward": { "get": { "tags": ["AdPools"], "summary": "Legacy fixed reward per post", "description": "Single `rewardPerPost` setting of a bounty pool (superseded by rates; nulls when unset).", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Reward", "content": { "application/json": { "schema": { "type": "object", "properties": { "adpool": { "$ref": "#/components/schemas/Address" }, "rewardPerPost": { "type": ["string", "null"] }, "maxPerCreator": { "type": ["integer", "null"] }, "decimals": { "type": ["integer", "null"] } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolReward", "security": [] } }, "/api/adpool/{adpool}/meta": { "get": { "tags": ["AdPools"], "summary": "AdPool branding", "description": "Banner, logo, colors, tagline and brief set by the manager (null when unset).", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "adpool": { "$ref": "#/components/schemas/Address" }, "meta": { "oneOf": [ { "type": "object", "additionalProperties": true, "description": "Pool branding" }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolMeta", "security": [] } }, "/api/adpool/{adpool}/leaderboard": { "get": { "tags": ["AdPools"], "summary": "AdPool creator leaderboard", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Cached leaderboard" } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolLeaderboard", "security": [] } }, "/api/adpool/{adpool}/submissions": { "get": { "tags": ["AdPools"], "summary": "Submitted posts of an AdPool", "description": "Off-chain submissions index; each row carries the public `verifiedCreator` badge.", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Submissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Submission: creator, contentUrl, dataHash, submittedAt…, verifiedCreator" } } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolSubmissions", "security": [] } }, "/api/adpool/{adpool}/metrics-source": { "get": { "tags": ["AdPools"], "summary": "An AdPool's metrics source", "description": "The data provider chosen for this pool, or the server default (`isDefault: true`).", "parameters": [ { "name": "adpool", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" }, "description": "AdPool contract address" } ], "responses": { "200": { "description": "Source", "content": { "application/json": { "schema": { "type": "object", "properties": { "adpool": { "$ref": "#/components/schemas/Address" }, "source": { "type": "string" }, "isDefault": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAdpoolByAdpoolMetricsSource", "security": [] } }, "/api/oracle/providers": { "get": { "tags": ["Verification"], "summary": "Oracle data providers", "description": "Providers that can measure posts and audiences: configured?, networks covered for post metrics and followers, trust level, cost hint, and the default. Official connections prove ownership only. No secrets.", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "string" }, "ownership": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "trust": { "type": "string" }, "configured": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "string" } }, "followers": { "type": "array", "items": { "type": "string" } }, "costHint": { "type": "string" } } } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiOracleProviders", "security": [] } }, "/api/capabilities": { "get": { "tags": ["Verification"], "summary": "Tracking capabilities per network", "description": "What SaTT can measure and verify right now, per network (ownership by OAuth / bio code, post listing, views, likes, comments, shares, saves, followers, quest actions): works | limited | unavailable, with the source and the last live probe summary. No secrets.", "responses": { "200": { "description": "Capability matrix", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Capability matrix + `probe` summary" } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiCapabilities", "security": [] } }, "/api/verify/methods": { "get": { "tags": ["Verification"], "summary": "Ownership verification methods per network", "description": "For each network: whether official OAuth and/or a one-time bio code can prove ownership.", "responses": { "200": { "description": "Methods by network", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true, "description": "Methods" } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiVerifyMethods", "security": [] } }, "/api/connect/providers": { "get": { "tags": ["Platform"], "summary": "Connectable networks", "description": "Which official network connections are configured on this server (no secrets).", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "object", "additionalProperties": true, "description": "Status per network" }, "vault": { "type": "boolean" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiConnectProviders", "security": [] } }, "/api/auth/providers": { "get": { "tags": ["Account"], "summary": "Sign-in providers", "description": "Which \"Continue with …\" buttons are live.", "responses": { "200": { "description": "Configured providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "google": { "type": "boolean" }, "facebook": { "type": "boolean" }, "twitter": { "type": "boolean" }, "linkedin": { "type": "boolean" }, "tiktok": { "type": "boolean" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiAuthProviders", "security": [] } }, "/api/receipts": { "get": { "tags": ["Receipts"], "summary": "List verified-account receipts", "description": "Newest first.", "parameters": [ { "name": "adpool", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "creator", "in": "query", "schema": { "$ref": "#/components/schemas/Address" }, "description": "Creator wallet" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Receipts", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReceipt" } }, "total": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiReceipts", "security": [] } }, "/api/receipts/{claimId}": { "get": { "tags": ["Receipts"], "summary": "One verified-account receipt", "description": "Receipt, signature, oracle and a server-side re-check (`verified`).", "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Bytes32" } } ], "responses": { "200": { "description": "Receipt", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicReceipt" }, { "type": "object", "properties": { "verified": { "type": "boolean" } } } ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiReceiptsByClaimId", "security": [] } }, "/api/quests": { "get": { "tags": ["Quests"], "summary": "List quest pools", "parameters": [ { "name": "edition", "in": "query", "schema": { "type": "string", "enum": ["crypto", "fiat"] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["live", "ended", "all"], "default": "live" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Quests", "content": { "application/json": { "schema": { "type": "object", "properties": { "quests": { "type": "array", "items": { "$ref": "#/components/schemas/Quest" } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuests", "security": [] } }, "/api/quests/capabilities": { "get": { "tags": ["Quests"], "summary": "Quest verification matrix", "description": "Configured verifiers and, per action kind and platform, the verification tier (auto | proof | honor).", "responses": { "200": { "description": "Capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": true, "description": "xApi, youtubeOAuth, youtubeKey, aggregator" }, "verification": { "type": "object", "additionalProperties": true, "description": "{ kind: { platform: auto | proof | honor } }" }, "auditHours": { "type": "integer" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuestsCapabilities", "security": [] } }, "/api/quests/{id}": { "get": { "tags": ["Quests"], "summary": "One quest", "description": "Advances the lifecycle lazily. `me` is null for anonymous callers.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Quest", "content": { "application/json": { "schema": { "type": "object", "properties": { "quest": { "$ref": "#/components/schemas/Quest" }, "me": { "oneOf": [ { "type": "object", "additionalProperties": true, "description": "Caller progress" }, { "type": "null" } ] }, "leaderboard": { "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Row" } }, { "type": "null" } ] } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuestsById", "security": [] } }, "/api/quests/by-pool/{edition}/{pool}": { "get": { "tags": ["Quests"], "summary": "Quest attached to a pool", "parameters": [ { "name": "edition", "in": "path", "required": true, "schema": { "type": "string", "enum": ["crypto", "fiat"] } }, { "name": "pool", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "AdPool address or dollar pool id" } ], "responses": { "200": { "description": "Quest", "content": { "application/json": { "schema": { "type": "object", "properties": { "quest": { "$ref": "#/components/schemas/Quest" }, "me": { "oneOf": [ { "type": "object", "additionalProperties": true, "description": "Caller progress" }, { "type": "null" } ] }, "leaderboard": { "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Row" } }, { "type": "null" } ] } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuestsByPoolByEditionByPool", "security": [] } }, "/api/quests/{id}/draw": { "get": { "tags": ["Quests"], "summary": "Draw publication (verify the draw)", "description": "Recompute root, seed and winners with `verifyQuestDraw` (@satt/shared) and compare the signer with `factory.oracle()`. 404 `not_frozen_yet` while the quest is live.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Draw", "content": { "application/json": { "schema": { "type": "object", "properties": { "publication": { "$ref": "#/components/schemas/QuestDrawPublication" }, "commitSignature": { "type": ["string", "null"] }, "status": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuestsByIdDraw", "security": [] } }, "/api/quests/{id}/proof/{participant}": { "get": { "tags": ["Quests"], "summary": "Merkle inclusion proof of an entrant", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "participant", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Bytes32" }, "description": "Participant hash" } ], "responses": { "200": { "description": "Proof", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "participant": { "$ref": "#/components/schemas/Bytes32" }, "tickets": { "type": "integer" } } }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Bytes32" } }, "merkleRoot": { "$ref": "#/components/schemas/Bytes32" } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiQuestsByIdProofByParticipant", "security": [] } }, "/api/fiat/config": { "get": { "tags": ["Dollar edition"], "summary": "Dollar edition settings", "description": "Test mode, currency, fee (bps of the budget, taken at funding), AI price and top-up / payout limits.", "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object", "properties": { "testMode": { "type": "boolean" }, "currency": { "type": "string" }, "stripe": { "type": "boolean" }, "feeBps": { "type": "integer" }, "aiPriceCents": { "type": "integer" }, "minTopupCents": { "type": "integer" }, "maxTopupCents": { "type": "integer" }, "minPayoutCents": { "type": "integer" }, "testTopupMaxCents": { "type": "integer" }, "testBalanceCapCents": { "type": "integer" }, "instantLogin": { "type": "boolean" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiFiatConfig", "security": [] } }, "/api/fiat/pools": { "get": { "tags": ["Dollar edition"], "summary": "List dollar AdPools", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "ended", "all"], "default": "active" } }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "description": "Network (use \"twitter\" for X)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Pools", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "$ref": "#/components/schemas/FiatPool" } } } } } } }, "400": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiFiatPools", "security": [] } }, "/api/fiat/pools/{id}": { "get": { "tags": ["Dollar edition"], "summary": "One dollar AdPool", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pool and leaderboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "pool": { "$ref": "#/components/schemas/FiatPool" }, "leaderboard": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Row" } } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "operationId": "getApiFiatPoolsById", "security": [] } }, "/api/account": { "get": { "tags": ["Account"], "summary": "My satt.com account", "description": "Account (no e-mail when none), Verified-creator status, directory listing, onboarding state, sign-in identities, linked wallets, configured sign-in providers.", "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "additionalProperties": true, "description": "Public account" }, "creator": { "$ref": "#/components/schemas/CreatorStatus" }, "directory": { "type": "object", "additionalProperties": true, "description": "Directory listing toggle" }, "onboarding": { "type": "object", "additionalProperties": true, "description": "Onboarding state" }, "identities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Sign-in identity" } }, "wallets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Linked wallet" } }, "signinProviders": { "type": "object", "additionalProperties": true, "description": "Configured providers" } } } } } }, "401": { "$ref": "#/components/responses/Error", "description": "Not signed in (`unauthorized`)" } }, "security": [ { "cookieAuth": [] } ], "operationId": "getApiAccount" } }, "/api/account/onboarding": { "get": { "tags": ["Account"], "summary": "My onboarding progress", "description": "4-step creator setup. `?audience=1` adds followers per network with an audience band.", "parameters": [ { "name": "audience", "in": "query", "schema": { "type": "string", "enum": ["1"] } } ], "responses": { "200": { "description": "Onboarding", "content": { "application/json": { "schema": { "type": "object", "properties": { "onboarding": { "type": "object", "properties": { "step": { "type": "integer" }, "completedAt": { "type": ["string", "null"] }, "skippedAt": { "type": ["string", "null"] }, "pending": { "type": "array", "items": { "type": "string" } }, "done": { "type": "integer" }, "total": { "type": "integer" } } }, "creator": { "$ref": "#/components/schemas/CreatorStatus" }, "directory": { "type": "object", "additionalProperties": true, "description": "Directory listing toggle" }, "audience": { "type": "object", "additionalProperties": true, "description": "Followers per network (only with audience=1)" } } } } } }, "401": { "$ref": "#/components/responses/Error", "description": "Not signed in (`unauthorized`)" } }, "security": [ { "cookieAuth": [] } ], "operationId": "getApiAccountOnboarding" } }, "/api/analytics": { "get": { "tags": ["Analytics"], "summary": "My stats", "description": "Per connected network: handle, followers, audience tier, verified owner, recent posts with their public numbers from the oracle data provider, and totals. Auth: `__session` cookie, or the wallet `SocialConnectRead` signature headers. Cached per connection (15 min; X 1 h). 503 `token_vault_unconfigured`.", "responses": { "200": { "description": "Analytics report", "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerKind": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "provider": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "trust": { "type": "string" }, "real": { "type": "boolean" } } }, "networks": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string", "enum": ["ok", "reauth", "rate_limited", "unavailable", "no_stats"] }, "handle": { "type": ["string", "null"] }, "verifiedOwner": { "type": "boolean" }, "followers": { "type": ["integer", "null"] }, "tier": { "type": ["string", "null"] }, "posts": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Post with stats" } }, "totals": { "type": "object", "additionalProperties": true, "description": "Totals" } } } } } } } } }, "401": { "$ref": "#/components/responses/Error", "description": "Not signed in (`unauthorized`)" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "cookieAuth": [] } ], "operationId": "getApiAnalytics" } } }, "components": { "schemas": { "Address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "degraded"] }, "version": { "type": "string" }, "commit": { "type": ["string", "null"] }, "chainId": { "type": "integer" }, "rpcConnected": { "type": "boolean" }, "blockNumber": { "type": ["string", "null"] } } }, "SattPrice": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sattUsd": { "type": "number" }, "bnbUsd": { "type": "number" }, "source": { "type": "string", "enum": ["dex-twap", "dex-spot", "fallback", "unavailable"] }, "twap": { "type": "boolean" }, "windowSeconds": { "type": "integer" }, "at": { "type": "integer", "description": "Unix milliseconds" } } }, "Creator": { "type": "object", "properties": { "id": { "type": "string", "description": "Directory id, or `satt:` for a listed SaTT account" }, "name": { "type": "string" }, "bio": { "type": ["string", "null"] }, "country": { "type": ["string", "null"] }, "niche": { "type": ["string", "null"] }, "contactable": { "type": "boolean", "description": "Reachable by e-mail through SaTT (the address is never exposed)" }, "followers": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "handle": { "type": ["string", "null"] }, "url": { "type": ["string", "null"] }, "followers": { "type": ["integer", "null"] } } } }, "verifiedCreator": { "type": "boolean", "description": "Public \"Verified creator\" badge" }, "creatorStatus": { "$ref": "#/components/schemas/CreatorStatus" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "Signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$" }, "Bytes32": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "OracleRegistration": { "type": "object", "required": ["oracle", "name", "endpoint", "platforms", "nonce", "deadline"], "properties": { "oracle": { "$ref": "#/components/schemas/Address" }, "name": { "type": "string", "maxLength": 60 }, "endpoint": { "type": "string", "description": "https URL or empty" }, "platforms": { "type": "string", "example": "tiktok,youtube", "description": "sorted, comma-separated" }, "nonce": { "type": "integer" }, "deadline": { "type": "integer", "description": "unix seconds, at most 1 h ahead" } } }, "OracleOffer": { "type": "object", "required": [ "oracle", "version", "platforms", "metrics", "freshnessSec", "pricing", "sla", "deadline" ], "properties": { "oracle": { "$ref": "#/components/schemas/Address" }, "version": { "type": "integer", "minimum": 1 }, "platforms": { "type": "string" }, "metrics": { "type": "string", "example": "views,likes,comments,shares" }, "freshnessSec": { "type": "integer" }, "pricing": { "type": "string", "description": "canonical JSON of {USD|TOKEN: {platform|default: [{upTo, price}], subscription}}" }, "sla": { "type": "string" }, "deadline": { "type": "integer" } } }, "MetricsReport": { "type": "object", "required": [ "oracle", "adpool", "dataHash", "platform", "views", "likes", "comments", "shares", "followers", "observedAt", "source", "jobId" ], "properties": { "oracle": { "$ref": "#/components/schemas/Address" }, "adpool": { "$ref": "#/components/schemas/Address" }, "dataHash": { "$ref": "#/components/schemas/Bytes32" }, "platform": { "type": "string" }, "views": { "type": "integer", "minimum": 0 }, "likes": { "type": "integer", "minimum": 0 }, "comments": { "type": "integer", "minimum": 0 }, "shares": { "type": "integer", "minimum": 0 }, "followers": { "type": "integer", "minimum": 0 }, "observedAt": { "type": "integer" }, "source": { "type": "string", "maxLength": 64 }, "jobId": { "type": "integer" } } }, "OwnershipMatch": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Address" }, "platform": { "type": "string" }, "handleHash": { "$ref": "#/components/schemas/Bytes32" }, "dataHash": { "$ref": "#/components/schemas/Bytes32" }, "method": { "type": "string", "enum": ["oauth", "profile_code"] }, "issuedAt": { "type": "integer" } } }, "SelfReport": { "type": "object", "properties": { "creator": { "$ref": "#/components/schemas/Address" }, "adpool": { "$ref": "#/components/schemas/Address" }, "dataHash": { "$ref": "#/components/schemas/Bytes32" }, "platform": { "type": "string" }, "views": { "type": "integer", "minimum": 0 }, "likes": { "type": "integer", "minimum": 0 }, "comments": { "type": "integer", "minimum": 0 }, "shares": { "type": "integer", "minimum": 0 }, "followers": { "type": "integer", "minimum": 0 }, "observedAt": { "type": "integer" }, "claimAmount": { "type": "string" }, "bond": { "type": "string" }, "deadline": { "type": "integer" } } }, "Challenge": { "type": "object", "properties": { "challenger": { "$ref": "#/components/schemas/Address" }, "selfReportId": { "type": "integer" }, "evidence": { "type": "string", "maxLength": 500 }, "deadline": { "type": "integer" } } }, "OracleJob": { "type": "object", "properties": { "jobId": { "type": "integer" }, "chainId": { "type": "integer" }, "edition": { "type": "string", "enum": ["crypto", "fiat"] }, "pool": { "type": "string" }, "adpool": { "$ref": "#/components/schemas/Address" }, "dataHash": { "$ref": "#/components/schemas/Bytes32" }, "url": { "type": "string" }, "platform": { "type": "string" }, "handle": { "type": ["string", "null"] }, "wallet": { "type": ["string", "null"] }, "ownershipProof": { "type": ["object", "null"], "properties": { "match": { "$ref": "#/components/schemas/OwnershipMatch" }, "signature": { "$ref": "#/components/schemas/Signature" }, "signer": { "$ref": "#/components/schemas/Address" } } }, "status": { "type": "string", "enum": ["open", "final", "expired"] }, "quorum": { "type": "integer" }, "assigned": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "integer" }, "due": { "type": "integer" }, "result": { "type": ["object", "null"] } } }, "CreatorStatus": { "type": "object", "properties": { "verifiedCreator": { "type": "boolean" }, "networks": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "handle": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["oauth", "bio_code", "unverified", "expired", "revoked"] } } } } }, "description": "\"Verified creator\": at least one network verified by its official OAuth connection AND every linked network verified (OAuth or bio code)." }, "NetworkRate": { "type": "object", "additionalProperties": true, "description": "Price of one social network in a pool: `platform`, and either audience `tiers` [{ minFollowers, perThousandFollowers, maxPerPost, maxCreators }] (fixed reward per post) or performance prices `perThousandViews`, `perLike`, `perShare`, `maxPerPost` (token base units as strings)." }, "AdpoolRates": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["bounty", "performance"] }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkRate" } }, "maxPostsPerCreator": { "type": "integer" } }, "description": "Per-network prices of an OracleSigned pool." }, "Campaign": { "type": "object", "additionalProperties": true, "description": "An AdPool: `record` (adpool, manager, name, createdAt), live on-chain `info` (token, rewardMode, startDate, endDate, feeBps, isBounty, isSatt, finalized, totalRewardPool, distributed, participantCount, dataUrl…), `ratios`, plus off-chain `meta` (branding), `reward` (legacy fixed reward) and `rates` (AdpoolRates) — each null when unset.", "properties": { "rates": { "oneOf": [ { "$ref": "#/components/schemas/AdpoolRates" }, { "type": "null" } ] } } }, "AdpoolStats": { "type": "object", "properties": { "participants": { "type": "integer", "description": "Distinct submitting creators" }, "validatedPosts": { "type": "integer", "description": "Distinct posts the Oracle attested" }, "verifiedCreators": { "type": "integer", "description": "Participants who are Verified creators" } } }, "FiatPool": { "type": "object", "additionalProperties": true, "description": "Dollar AdPool: id, title, brief, platforms, mode (bounty | performance | quest | legacy proportional), rates, budgetCents, feeCents, netCents, spentCents, remainingCents, currency, endsAt, status, owner.displayName, submissionsCount, meta." }, "Quest": { "type": "object", "additionalProperties": true, "description": "QuestView: id, edition (crypto | fiat), poolRef, chainId, title, prize, budget, currency, startsAt, endsAt, drawAt, maxTicketsPerPerson, allowHonor, requireVerifiedCreator, status (live | frozen | drawn | final | cancelled), phase, entrants, totalTickets, actions[] (kind, platform, tickets, verification auto | proof | honor), commitment." }, "QuestDrawPublication": { "type": "object", "additionalProperties": true, "description": "Everything needed to recompute the draw (`verifyQuestDraw` in @satt/shared): version, questId, entries [(participant hash, tickets)], merkleRoot, totalTickets, beacon { chainId, blockNumber, blockHash }, seed, slots, disqualified, winners, signature, oracle. Before the draw, seed/winners/signature are null (commitment only)." }, "PublicReceipt": { "type": "object", "properties": { "claimId": { "$ref": "#/components/schemas/Bytes32" }, "receipt": { "type": "object", "properties": { "version": { "type": "integer" }, "chainId": { "type": "integer" }, "adpool": { "$ref": "#/components/schemas/Address" }, "creator": { "$ref": "#/components/schemas/Address" }, "dataHash": { "$ref": "#/components/schemas/Bytes32" }, "claimId": { "$ref": "#/components/schemas/Bytes32" }, "platform": { "type": "string" }, "handleHash": { "$ref": "#/components/schemas/Bytes32" }, "handle": { "type": "string" }, "verification": { "type": "string", "enum": ["oauth", "profile_code"] }, "metricsSource": { "type": "string" }, "verifiedAt": { "type": "integer" }, "issuedAt": { "type": "integer" } } }, "signature": { "$ref": "#/components/schemas/Signature" }, "oracle": { "$ref": "#/components/schemas/Address" }, "currentOracle": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "primaryType": { "const": "VerifiedAccountReceipt" }, "domain": { "type": "object", "additionalProperties": true }, "types": { "type": "object", "additionalProperties": true }, "txHash": { "type": ["string", "null"] } }, "description": "Verify with @satt/shared `verifyVerifiedAccountReceipt` against `factory.oracle()`; join to the chain by `usedClaims(claimId)` / `RewardClaimed(dataHash)`." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "__session", "description": "satt.com account session (e-mail magic link or Google / Facebook / X / LinkedIn / TikTok sign-in). Writes also require an allowed `Origin` header (CSRF)." } } } }