{"openapi":"3.0.4","info":{"title":"Data Fabric API","description":"Data Fabric API provides access to various blockchain datasets and analytics.\n\nThe NodeIntelligence API offering within Data Fabric provides asynchronous querying capabilities \nfor Tron blockchain data correlation with IP addresses.\n\nNodeIntelligence API supports three main lookup types:\n- Transaction Hash Lookup: Get IP data and metadata for a transaction hash\n- Crypto Address Lookup: Get IP data and transaction hashes for a crypto address  \n- Node Address Lookup: Get associated on-chain Tron transactions for associated address (IPV4, IPV6 etc.)\n\nThe results of the endpoints will be links to downloadable files. Supported file formats are JSON arrays and CSV.\n\nThe data will contain fields:\ntimestamp, ip, hash, city, country, subdivision, isAnonymousVpn, isTorExitNode, address, year, month, day, date, isAnonymous, isHostingProvider, isp, organization, network\n\n**Authentication**: All endpoints require a valid x-access-key, x-access-sign, and x-access-timestamp headers.\n","version":"0.1.9"},"servers":[{"url":"https://data-fabric.crypteng.prod.aws.elliptic.local/","description":"Production server"},{"url":"https://data-fabric.crypteng.dev.aws.elliptic.local/","description":"Staging server"}],"paths":{"/v1/node-intelligence/tron/transactions":{"post":{"summary":"Submit transaction hashses for lookup","description":"Submit an asynchronous query to lookup IP data for a Tron transaction hashes.","operationId":"submitTransactionLookup","tags":["Tron NodeIntelligence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionLookupRequest"},"example":{"hashes":["7c8e92087b7ae9752dda3de40e3f4a0b7c8e92087b7ae9752dda3de40e3f4a0b","00000000043a6d59c506cf388c8c58e256dc7222e662c50cb4f165155fb45aec"]}}}},"responses":{"202":{"description":"Query accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/node-intelligence/tron/wallet":{"post":{"summary":"Submit crypto wallet address lookup","description":"Submit an asynchronous query to lookup IP data for a Tron crypto wallet address","operationId":"submitWalletLookup","tags":["Tron NodeIntelligence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletLookupRequest"},"examples":{"basic":{"summary":"Basic wallet lookup","value":{"wallet":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}},"with_date_filter":{"summary":"Wallet lookup with date filter","value":{"wallet":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","filters":{"date":{"operation":"gt","value":"2025-01-01"}}}},"with_boolean_filters":{"summary":"Wallet lookup with boolean filters","value":{"wallet":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","filters":{"is_tor_exit_node":true,"is_anonymous":false}}},"with_mixed_filters":{"summary":"Wallet lookup with date and boolean filters","value":{"wallet":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","filters":{"date":{"operation":"between","lower":"2025-01-01","upper":"2025-01-31"},"is_tor_exit_node":true,"is_hosting_provider":false}}}}}}},"responses":{"202":{"description":"Query accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/node-intelligence/tron/node":{"post":{"summary":"Submit node address for lookup","description":"Submit an asynchronous query to lookup Tron transactions for known node address","operationId":"submitNodeLookup","tags":["Tron NodeIntelligence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeLookupRequest"},"examples":{"basic":{"summary":"Basic node lookup","value":{"node":"192.168.0.1"}},"with_date_filter":{"summary":"Node lookup with date range filter","value":{"node":"192.168.0.1","filters":{"date":{"operation":"between","lower":"2025-01-01","upper":"2025-03-31"}}}},"with_boolean_filters":{"summary":"Node lookup with boolean filters","value":{"node":"192.168.0.1","filters":{"is_anonymous":true,"is_hosting_provider":false}}}}}}},"responses":{"202":{"description":"Query accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/node-intelligence/queries/{query_id}":{"get":{"summary":"Poll query","description":"Check if query is complete and ready for results","operationId":"pollQuery","tags":["Tron NodeIntelligence"],"parameters":[{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Query status and results (if complete)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QueryPendingResponse"},{"$ref":"#/components/schemas/QuerySucceededResponse"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"TransactionLookupRequest":{"type":"object","required":["hashes"],"properties":{"hashes":{"type":"array","items":{"type":"string","description":"Transaction hash","example":["7c8e92087b7ae9752dda3de40e3f4a0b7c8e92087b7ae9752dda3de40e3f4a0b","00000000043a6d59c506cf388c8c58e256dc7222e662c50cb4f165155fb45aec"]},"description":"List of transaction hashes to look up"},"format":{"type":"string","enum":["JSON_ARRAY","CSV"],"description":"Desired output file format, one of \"JSON_ARRAY\" or \"CSV\". Default is \"JSON_ARRAY\"","default":"JSON_ARRAY"}}},"WalletLookupRequest":{"type":"object","required":["wallet"],"properties":{"wallet":{"type":"string","description":"Wallet address","example":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"},"filters":{"type":"object","properties":{"date":{"$ref":"#/components/schemas/DateFilterValue"},"is_tor_exit_node":{"type":"boolean","description":"Filter for Tor exit nodes"},"is_anonymous":{"type":"boolean","description":"Filter for anonymous IPs"},"is_hosting_provider":{"type":"boolean","description":"Filter for hosting provider IPs"}},"description":"Optional filters to apply to the query","additionalProperties":false},"format":{"type":"string","enum":["JSON_ARRAY","CSV"],"description":"Desired output file format, one of \"JSON_ARRAY\" or \"CSV\". Default is \"JSON_ARRAY\"","default":"JSON_ARRAY"}}},"NodeLookupRequest":{"type":"object","required":["node"],"properties":{"node":{"type":"string","description":"Node address (IPV4, IPV6 etc.)","example":"192.168.0.1"},"filters":{"type":"object","properties":{"date":{"$ref":"#/components/schemas/DateFilterValue"},"is_tor_exit_node":{"type":"boolean","description":"Filter for Tor exit nodes"},"is_anonymous":{"type":"boolean","description":"Filter for anonymous IPs"},"is_hosting_provider":{"type":"boolean","description":"Filter for hosting provider IPs"}},"description":"Optional filters to apply to the query","additionalProperties":false},"format":{"type":"string","enum":["JSON_ARRAY","CSV"],"description":"Desired output file format, one of \"JSON_ARRAY\" or \"CSV\". Default is \"JSON_ARRAY\"","default":"JSON_ARRAY"}}},"QueryResponse":{"type":"object","required":["query_id","status"],"properties":{"query_id":{"type":"string","format":"uuid","description":"Unique identifier for the query"},"status":{"type":"string","enum":["ACCEPTED"],"description":"Query acceptance status"}}},"BooleanFilter":{"type":"object","required":["field","value"],"properties":{"field":{"type":"string","enum":["is_tor_exit_node","is_anonymous","is_hosting_provider"],"description":"Boolean field to filter on"},"value":{"type":"boolean","description":"Boolean value to filter by"}},"example":{"field":"is_tor_exit_node","value":true}},"DateFilter":{"type":"object","required":["field","operation"],"properties":{"field":{"type":"string","enum":["date"],"description":"Date field to filter on, in yyyy-mm-dd format"},"operation":{"type":"string","enum":["gt","lt","eq","between"],"description":"Filter operation:\n- gt: Greater than\n- lt: Less than  \n- eq: Equal to\n- between: Between two values (requires lower and upper fields)\n"},"value":{"type":"string","format":"date","description":"Date value (for gt, lt, eq operations)"},"lower":{"type":"string","format":"date","description":"Lower bound date (required for between operation)"},"upper":{"type":"string","format":"date","description":"Upper bound date (required for between operation)"}},"example":{"field":"date","operation":"gt","value":"2025-01-01"}},"DateFilterValue":{"type":"object","required":["operation"],"properties":{"operation":{"type":"string","enum":["gt","lt","eq","between"],"description":"Filter operation:\n- gt: Greater than\n- lt: Less than  \n- eq: Equal to\n- between: Between two values (requires lower and upper fields)\n"},"value":{"type":"string","format":"date","description":"Date value (for gt, lt, eq operations)"},"lower":{"type":"string","format":"date","description":"Lower bound date (required for between operation)"},"upper":{"type":"string","format":"date","description":"Upper bound date (required for between operation)"}},"example":{"operation":"gt","value":"2025-01-01"}},"QueryPendingResponse":{"type":"object","required":["statement_id","status"],"properties":{"statement_id":{"type":"string","format":"uuid","description":"Statement UUID"},"status":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["PENDING","RUNNING"]}}}},"example":{"statement_id":"01f0ae69-c9a5-14c5-830c-532e7c790b05","status":{"state":"PENDING"}}},"QuerySucceededResponse":{"type":"object","required":["statement_id","status","manifest","result"],"properties":{"statement_id":{"type":"string","format":"uuid","description":"Statement UID"},"status":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["SUCCEEDED","FAILED","CANCELED"]}}},"manifest":{"type":"object","properties":{"format":{"type":"string","example":"JSON_ARRAY"},"schema":{"$ref":"#/components/schemas/ResultSchema"},"total_chunk_count":{"type":"integer"},"total_row_count":{"type":"integer"},"total_byte_count":{"type":"integer"},"truncated":{"type":"boolean"}}},"result":{"type":"object","properties":{"external_links":{"type":"array","items":{"$ref":"#/components/schemas/ExternalLink"}}}}}},"ResultSchema":{"type":"object","properties":{"column_count":{"type":"integer"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnInfo"}}}},"ColumnInfo":{"type":"object","properties":{"name":{"type":"string"},"type_text":{"type":"string"},"type_name":{"type":"string"},"position":{"type":"integer"}}},"ExternalLink":{"type":"object","required":["external_link","expiration"],"properties":{"chunk_index":{"type":"integer"},"row_offset":{"type":"integer"},"row_count":{"type":"integer"},"byte_count":{"type":"integer"},"external_link":{"type":"string","format":"uri","description":"Presigned S3 URL for downloading result data"},"expiration":{"type":"string","format":"date-time","description":"When the presigned URL expires"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INVALID_INPUT","message":"Invalid transaction hash format. Expected 64-character hexadecimal string."}}}},"Unauthorized":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"UNAUTHORIZED","message":"Invalid or missing API key. Please check your X-API-Key header."}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"QUERY_NOT_FOUND","message":"Query not found or has expired"}}}},"InternalServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INTERNAL_ERROR","message":"An unexpected error occurred while processing your request"}}}}},"securitySchemes":{"EllipticAuth":{"type":"http","scheme":"bearer","description":"Elliptic HMAC-SHA256 authentication requires three headers for all requests:\n\n**Required Headers:**\n1. **x-access-key**: Your API key\n2. **x-access-sign**: HMAC-SHA256 signature of the request  \n3. **x-access-timestamp**: Current timestamp in milliseconds\n\n**Signature Calculation:**\n```\nREQUEST_TEXT = TIME_OF_REQUEST + HTTP_METHOD + HTTP_PATH_LOWERCASE + REQUEST_BODY\nSIGNATURE = Base64(HMAC-SHA256(REQUEST_TEXT, Base64.decode(SECRET)))\n```\n\nWhere:\n- **TIME_OF_REQUEST**: Unix timestamp in milliseconds (same as x-access-timestamp header)\n- **HTTP_METHOD**: GET, POST, etc. (uppercase)\n- **HTTP_PATH_LOWERCASE**: API path including query string (lowercase)\n- **REQUEST_BODY**: JSON string for POST requests, or \"{}\" for GET requests or when no body\n\n**Example REQUEST_TEXT for POST /v1/node-intelligence/example/path/transactions:**\n```\n1634567890123POST/v1/node-intelligence/example/path/transactions{\"hashes\":[\"abc123\"]}\n```\n\n**Example REQUEST_TEXT for GET /v1/node-intelligence/example/path/12345:**\n```\n1634567890123GET/v1/node-intelligence/example/path/12345{}\n```\n\n**Example Headers:**\n```\nx-access-key: your_api_key_here\nx-access-sign: generated_signature_here  \nx-access-timestamp: 1634567890123\n```\n"}}},"security":[{"EllipticAuth":[]}],"tags":[{"name":"Tron NodeIntelligence","description":"Tron blockchain data lookup operations"}]}