{ "openapi": "3.1.0", "info": { "title": "Agent Exchange Trends", "version": "1.0.0", "summary": "Keyless hourly trending lists with an accumulating archive; paid archive via x402.", "description": "Google Trends trending searches (US, GB, CA, AU, IN, DE, FR, BR, JP, MX), English Wikipedia most-read (WIKI) and the Hacker News front page (HN), refreshed hourly. Free within 7 days; older archive paid per call in USDC on Base. Errors are { error, code, message, hint, docs }.", "termsOfService": "https://trends.agentexchange.work/terms", "contact": { "name": "Agent Exchange", "url": "https://network.agentexchange.work" }, "license": { "name": "CC BY 4.0 (derived fields)", "url": "https://creativecommons.org/licenses/by/4.0/" }, "x-pricing": "https://trends.agentexchange.work/pricing", "x-x402-manifest": "https://trends.agentexchange.work/.well-known/x402", "x-mcp": "https://trends.agentexchange.work/mcp" }, "servers": [ { "url": "https://trends.agentexchange.work" } ], "paths": { "/trends/latest.json": { "get": { "operationId": "trendingNowQuery", "summary": "Current list by ?geo=", "parameters": [ { "name": "geo", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "BR", "JP", "MX", "WIKI", "HN" ] }, "description": "List id: a Google Trends country code, WIKI (English Wikipedia) or HN (Hacker News)." } ], "responses": { "200": { "description": "The current list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/latest/{geo}.json": { "get": { "operationId": "trendingNow", "summary": "Current list for one geo", "parameters": [ { "name": "geo", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "BR", "JP", "MX", "WIKI", "HN" ] }, "description": "List id: a Google Trends country code, WIKI (English Wikipedia) or HN (Hacker News)." } ], "responses": { "200": { "description": "The current list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/day/{date}/{geo}.json": { "get": { "operationId": "dayArchive", "summary": "Everything that trended on a day (free for the last 7 days, then $0.01)", "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "UTC day, YYYY-MM-DD (WIKI: the pageviews day)" }, { "name": "geo", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "BR", "JP", "MX", "WIKI", "HN" ] }, "description": "List id: a Google Trends country code, WIKI (English Wikipedia) or HN (Hacker News)." } ], "responses": { "200": { "description": "The day file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DayResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v1 requirements in accepts[] plus the envelope fields code, message, hint, docs; the payment-required header carries the v2 form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": { "version": 1, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "facilitator": "https://facilitator.payai.network", "headers_v2": true } } ] }, "x-free-window-days": 7 } }, "/trends/archive/{geo}/{from}/{to}.json": { "get": { "operationId": "archiveRange", "summary": "Up to 90 day files in one response ($0.25)", "parameters": [ { "name": "geo", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "BR", "JP", "MX", "WIKI", "HN" ] }, "description": "List id: a Google Trends country code, WIKI (English Wikipedia) or HN (Hacker News)." }, { "name": "from", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "first day, inclusive" }, { "name": "to", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "last day, inclusive; at most 90 days after from" } ], "responses": { "200": { "description": "Day files keyed by date; missing lists days without a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v1 requirements in accepts[] plus the envelope fields code, message, hint, docs; the payment-required header carries the v2 form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": { "version": 1, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "facilitator": "https://facilitator.payai.network", "headers_v2": true } } ] } } }, "/trends/topic/{slug}.json": { "get": { "operationId": "topicHistory", "summary": "Where and when a topic trended, last 7 days", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,95}$" }, "description": "Topic slug as printed in item.slug." } ], "responses": { "200": { "description": "Appearances joined with day-file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/topic/{slug}/history.json": { "get": { "operationId": "topicHistoryFull", "summary": "Full topic history ($0.05)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,95}$" }, "description": "Topic slug as printed in item.slug." } ], "responses": { "200": { "description": "Every appearance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicResponse" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v1 requirements in accepts[] plus the envelope fields code, message, hint, docs; the payment-required header carries the v2 form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": { "version": 1, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "facilitator": "https://facilitator.payai.network", "headers_v2": true } } ] } } }, "/trends/feed.xml": { "get": { "operationId": "newEntriesFeed", "summary": "Atom feed of items that entered a list in the last 24 hours", "parameters": [ { "name": "geo", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "IN", "DE", "FR", "BR", "JP", "MX", "WIKI", "HN" ] }, "description": "List id: a Google Trends country code, WIKI (English Wikipedia) or HN (Hacker News)." } ], "responses": { "200": { "description": "Atom feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/live.json": { "get": { "operationId": "live", "summary": "Last run, runs, per-source status", "responses": { "200": { "description": "Run meta", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "Liveness", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/a2a": { "post": { "operationId": "a2a", "summary": "A2A JSON-RPC 2.0 (protocol 0.3.0): message/send, tasks/get, tasks/cancel. Free skills complete at once; paid skills answer a Task in state input-required with x402.payment.required (the same accepts[] as the HTTP 402); reply on the taskId with x402.payment.status payment-submitted and x402.payment.payload (a2a-x402 v0.1).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string", "enum": [ "message/send", "tasks/get", "tasks/cancel" ] }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC response (result is a Task)", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "too many unpaid requests in a minute (JSON-RPC error -32000)" } } }, "get": { "operationId": "a2aPointer", "summary": "Pointer to the agent card and the A2A methods", "responses": { "200": { "description": "pointer", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP server (Streamable HTTP, JSON-RPC 2.0): initialize, tools/list, tools/call for trending_now, topic_history, day_archive", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/listings": { "post": { "operationId": "paidListing", "summary": "List one https URL for 30 days ($1.00)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 200 }, "payTo": { "type": "string" } }, "required": [ "url", "name" ] } } } }, "responses": { "201": { "description": "Listed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required: x402 v1 requirements in accepts[] plus the envelope fields code, message, hint, docs; the payment-required header carries the v2 form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "404": { "description": "Not found (JSON envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.00" }, "protocols": [ { "x402": { "version": 1, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xc91cE6291eDC0713ec753BAFBA002506ffb2b95c", "facilitator": "https://facilitator.payai.network", "headers_v2": true } } ] } } }, "/listings.json": { "get": { "operationId": "listings", "summary": "Current paid listings and terms (free)", "responses": { "200": { "description": "Listings", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Item": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "google-trends", "wikipedia", "hacker-news" ] }, "geo": { "type": "string" }, "rank": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "approx_traffic": { "type": "string", "description": "Google Trends' rounded figure, e.g. 5000+" }, "score": { "type": "integer", "description": "Wikipedia views or Hacker News points" }, "comments": { "type": "integer" }, "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "source": { "type": [ "string", "null" ] } } } }, "hn_url": { "type": "string" }, "published": { "type": "string" }, "seen_at": { "type": "string", "format": "date-time" }, "first_seen": { "type": "string", "format": "date-time" }, "hours_trending": { "type": "integer" }, "days_trending": { "type": "integer" }, "peak_rank": { "type": "integer" }, "rank_history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "rank": { "type": "integer" } } } }, "rising": { "type": "boolean" }, "persistent": { "type": "boolean" }, "topic": { "type": "string", "format": "uri" } }, "required": [ "source", "geo", "rank", "title", "slug", "url", "seen_at", "first_seen", "peak_rank" ] }, "ListResponse": { "type": "object", "properties": { "list": { "type": "string" }, "geo": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] }, "run": { "type": [ "integer", "null" ] }, "data_date": { "type": "string" }, "count": { "type": "integer" }, "rising": { "type": "integer" }, "persistent": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "attribution": { "type": "object" }, "license": { "type": "string" } } }, "DayItem": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "entry_rank": { "type": "integer" }, "peak_rank": { "type": "integer" }, "last_rank": { "type": "integer" }, "runs_seen": { "type": "integer", "description": "hourly runs the item was in the list that day (Wikipedia: one per day)" }, "approx_traffic": { "type": "string" }, "score_max": { "type": "integer" }, "score_last": { "type": "integer" }, "comments_max": { "type": "integer" }, "news": { "type": "array" } } }, "DayResponse": { "type": "object", "properties": { "list": { "type": "string" }, "date": { "type": "string" }, "count": { "type": "integer" }, "paid": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DayItem" } } } }, "ArchiveResponse": { "type": "object", "properties": { "list": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "days_requested": { "type": "integer" }, "days_present": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string" } }, "days": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DayItem" } } } } } } }, "TopicResponse": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "lists": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } }, "days": { "type": "integer" }, "appearances_total": { "type": "integer" }, "window": { "type": "string" }, "appearances": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "list": { "type": "string" }, "source": { "type": "string" }, "rank": { "type": "integer" }, "first_seen": { "type": "string" }, "day_file": { "type": "string" }, "details": { "oneOf": [ { "$ref": "#/components/schemas/DayItem" }, { "type": "null" } ] } } } } } }, "Error": { "type": "object", "required": [ "error", "code", "message", "hint", "docs" ], "properties": { "error": { "type": "string", "description": "machine code, e.g. not_found, unknown_geo, invalid_date, no_data, unknown_topic, method_not_allowed" }, "code": { "type": "integer", "description": "HTTP status" }, "message": { "type": "string" }, "hint": { "type": "string" }, "docs": { "type": "string", "format": "uri" } } }, "X402Challenge": { "type": "object", "properties": { "x402Version": { "type": "integer", "const": 1 }, "error": { "type": "string" }, "code": { "type": "integer", "const": 402 }, "message": { "type": "string" }, "hint": { "type": "string" }, "docs": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "maxAmountRequired": { "type": "string", "description": "USDC base units (6 decimals)" }, "resource": { "type": "string" }, "payTo": { "type": "string" }, "asset": { "type": "string" } } } } } } } } }