{ "openapi": "3.1.0", "info": { "title": "xspy — x402 Pay-per-Request Twitter Intelligence API", "version": "1.0.0", "description": "Real-time KOL, smart-follower, and on-chain signal intelligence APIs. All endpoints are payable per request in USDC on Base or Solana using the x402 HTTP 402 payment protocol. No long-term API keys required.", "x-guidance": "This is a pay-per-request API. To call any endpoint:\n1. Make the request without payment → you will receive HTTP 402 with exact payment details.\n2. Pay the requested amount to the address in the 402 response (USDC on the chosen network).\n3. Retry the exact same request, attaching the payment proof in the X-PAYMENT header (or use an x402-compatible client).\nSee https://x402.org and the Coinbase x402 docs for client libraries and agent integration patterns. Prices and descriptions are the source of truth for discovery and billing." }, "servers": [ { "url": "https://xspy.pro", "description": "Production" } ], "paths": { "/api/v1/pro/trending-accounts": { "get": { "summary": "Trending Twitter/X accounts among crypto smart money for a selected time window (1h–7d), ranked by smart-follower activity.", "description": "Trending Twitter/X accounts among crypto smart money for a selected time window (1h–7d), ranked by smart-follower activity.", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "3h", "6h", "24h", "7d" ], "default": "24h" }, "description": "Time window for trending calculation", "example": "24h" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "1h", "3h", "6h", "24h", "7d" ], "description": "Trending time window" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": { "window": "24h" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": [ { "twitter": "0xexample", "smartFollowersCount": 512 } ], "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.10" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/is-smart-follower": { "get": { "summary": "Determine whether a Twitter/X account is a 'smart follower'", "description": "Determine whether a Twitter/X account is a 'smart follower' — a high-signal crypto account — returning a boolean and a descriptive label.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "isSmartFollower": false, "label": "" }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.03" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/smart-followers/count": { "get": { "summary": "Total number of smart followers (high-signal crypto accounts) for a given Twitter/X account.", "description": "Total number of smart followers (high-signal crypto accounts) for a given Twitter/X account.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "totalCount": 13, "meta": { "resolved": true } }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.02" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/smart-followers": { "get": { "summary": "Top smart followers (high-signal crypto accounts) of a Twitter/X account, with profiles and follower metrics.", "description": "Top smart followers (high-signal crypto accounts) of a Twitter/X account, with profiles and follower metrics.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "smartFollowers": [ { "twitterId": "837985489", "name": "Damien", "twitter": "0xDamien", "followersCount": 30123, "smartFollowersCount": 837 } ], "totalCount": 13, "meta": { "resolved": true } }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.05" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/tweets-with-ca-cache": { "get": { "summary": "Cached lookup of a Twitter/X account's recent tweets mentioning token contract addresses (CAs), with detected chain and address. Fast.", "description": "Cached lookup of a Twitter/X account's recent tweets mentioning token contract addresses (CAs), with detected chain and address. Fast.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "source": "database", "topUndeletedTweets": [ { "tweetId": "2059974300447248879", "twitterHandle": "gigaevm", "chain": "BASE", "ca": "0x7AC13Be3939f75E28135097A1b6398Fe024eCBa3", "content": "the community deployed a token for me on Base.", "tweetTime": "2026-05-28T12:25:20.000Z" } ], "undeletedCACount": 1, "undeletedTweetCount": 1 }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.12" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/tweets-with-ca": { "get": { "summary": "Real-time crawl of a Twitter/X account's recent tweets mentioning token contract addresses (CAs), with detected chain and address. Freshest data.", "description": "Real-time crawl of a Twitter/X account's recent tweets mentioning token contract addresses (CAs), with detected chain and address. Freshest data.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "source": "database", "topUndeletedTweets": [ { "tweetId": "2059974300447248879", "twitterHandle": "gigaevm", "chain": "BASE", "ca": "0x7AC13Be3939f75E28135097A1b6398Fe024eCBa3", "content": "the community deployed a token for me on Base.", "tweetTime": "2026-05-28T12:25:20.000Z" } ], "undeletedCACount": 1, "undeletedTweetCount": 1 }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.25" } }, "protocols": [ { "x402": {} } ] } } }, "/api/v1/pro/twitter/{username}/username-history": { "get": { "summary": "Historical Twitter/X handle changes for an account, with change timestamps.", "description": "Historical Twitter/X handle changes for an account, with change timestamps.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "description": "Twitter/X handle without the leading @", "example": "elonmusk" } ], "requestBody": { "required": true, "description": "x402 agent invocation envelope (HTTP method, path/query params). Send as JSON when describing how to call this resource; the live call is still a normal HTTP GET with payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "DELETE" ] }, "queryParams": { "type": "object", "properties": {} }, "pathParams": { "type": "object", "properties": { "username": { "type": "string", "description": "Twitter/X handle (without the @)" } } } }, "required": [ "type", "method" ], "additionalProperties": false }, "example": { "type": "http", "queryParams": {}, "pathParams": { "username": "elonmusk" } } } } }, "responses": { "200": { "description": "Successful response with intelligence data", "content": { "application/json": { "example": { "data": { "history": [ { "username": "oldhandle", "changedAt": "2025-01-01T00:00:00.000Z" } ] }, "code": 200, "status": true, "message": "success" } } } }, "402": { "description": "Payment Required. Pay using the x402 protocol (USDC on Base or Solana) and retry with the payment header." } }, "x-payment-info": { "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.10" } }, "protocols": [ { "x402": {} } ] } } } } }