> For the complete documentation index, see [llms.txt](https://coat.gitbook.io/tokeninfo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coat.gitbook.io/tokeninfo.ai/inspection-api.md). # Inspection API ## User Transaction and Token Price History Endpoints ### Overview These endpoints are designed to retrieve detailed transaction information for a specific user on a given blockchain network and to provide historical price data for a specific token. Both endpoints offer extensive filtering options, allowing users to customize the results based on date ranges, sort orders, and more. ### Endpoints #### 1. Get User Transaction Stats by Address **Endpoint**: `GET /inspection/wallet/:chain/:address/tx` **Description**: Retrieves transaction statistics for a specified user address on a given blockchain network. The data can be filtered and sorted by various parameters such as transaction type, date range, and more. *** #### 2. Get Token Price History **Endpoint**: `GET /inspection/token/:chain/:address/price/history` **Description**: Retrieves historical price data for a specific token on a given blockchain network. The data can be filtered by date range, grouped by time intervals, and sorted. *** ### Endpoint 1: Get User Transaction Stats by Address #### Request Parameters **URL Parameters** * **chain**: * **Type**: Number * **Description**: The blockchain network chain ID. Supported chains: * `1`: Ethereum Mainnet (default) * `56`: Binance Smart Chain * `800`: Solana Mainnet * `137`: Polygon Mainnet * `42161`: Arbitrum Mainnet * **Required**: Yes * **address**: * **Type**: String * **Description**: The wallet address of the user. * **Required**: Yes **Query Parameters** * **start**: * **Type**: Number * **Description**: The start date filter in seconds (Unix timestamp). Defaults to 24 hours earlier. * **Required**: No * **end**: * **Type**: Number * **Description**: The end date filter in seconds (Unix timestamp). Defaults to the current date. * **Required**: No * **sort**: * **Type**: String * **Description**: Sort order of the results, either `asc` or `desc`. Defaults to `desc`. * **Required**: No * **limit**: * **Type**: Number * **Description**: The number of results per page. Defaults to `300`, maximum `300`. * **Required**: No * **page**: * **Type**: Number * **Description**: The page number for paginated results. Defaults to `1`. * **Required**: No * **time**: * **Type**: String * **Description**: Type of results, either `realtime` or `history`. Defaults to `realtime`. * **Required**: No * **type**: * **Type**: String * **Description**: Type of transactions to retrieve. Options are `contract`, `transfer`, or `trade`. Defaults to `trade`. * **Required**: No #### Success Response * **Status Code**: `200 OK` * **Response Body**: ```json { "status": true, "data": { "data": [ { "action": "BUY", "buyUsd": 123.45, "buyAmount": 10, "buyToken": { "name": "TokenName", "symbol": "TKN", "address": "0xTokenAddress1" }, "sellUsd": 100.00, "sellAmount": 5, "sellToken": { "name": "TokenName", "symbol": "TKN", "address": "0xTokenAddress2" }, "buyer": "0xBuyerAddress", "seller": "0xSellerAddress", "date": "2023-08-20T12:34:56Z", "hash": "0xTransactionHash", "from": "0xFromAddress", "contract": "0xContractAddress", "protocol": "ProtocolName" } // More transactions... ] } } ``` #### Error Responses 1. **Missing Address** * **Status Code**: `400 Bad Request` * **Response Body**: ```json { "status": false, "msg": "Missing parameters. Expecting: address" } ``` 2. **Unsupported Chain** * **Status Code**: `400 Bad Request` * **Response Body**: ```json { "status": false, "msg": "Unsupported chain ID" } ``` 3. **Internal Server Error** * **Status Code**: `500 Internal Server Error` * **Response Body**: ```json { "status": false, "msg": "An unexpected error occurred." } ``` *** ### Endpoint 2: Get Token Price History #### Request Parameters **URL Parameters** * **chain**: * **Type**: Number * **Description**: The blockchain network chain ID. Supported chains: * `1`: Ethereum Mainnet (default) * `56`: Binance Smart Chain * `97`: Binance Smart Chain Testnet * `800`: Solana Mainnet * `137`: Polygon Mainnet * `8453`: Base Mainnet * `42161`: Arbitrum Mainnet * **Required**: Yes * **address**: * **Type**: String * **Description**: The address of the token. * **Required**: Yes **Query Parameters** * **start**: * **Type**: Number * **Description**: The start date filter in seconds (Unix timestamp). Defaults to 24 hours earlier. * **Required**: No * **end**: * **Type**: Number * **Description**: The end date filter in seconds (Unix timestamp). Defaults to the current date. * **Required**: No * **sort**: * **Type**: String * **Description**: Sort order of the results, either `asc` or `desc`. Defaults to `desc`. * **Required**: No * **limit**: * **Type**: Number * **Description**: The number of results per page. Defaults to `300`, maximum `300`. * **Required**: No * **page**: * **Type**: Number * **Description**: The page number for paginated results. Defaults to `1`. * **Required**: No * **group**: * **Type**: String * **Description**: Aggregates results by time interval. Options: `day`, `min`, `hr`, `mon`, `wk`, `yr`. Defaults to `day`. * **Required**: No #### Success Response * **Status Code**: `200 OK` * **Response Body**: ```json { "status": true, "data": { "prices": [ { "usd": 123.45, "volume": 100000, "marketCap": 1000000, "date": "2023-08-20T12:34:56Z" } // More price entries... ] } } ``` #### Error Responses 1. **Missing Address** * **Status Code**: `400 Bad Request` * **Response Body**: ```json { "status": false, "msg": "Missing parameters. Expecting: address" } ``` 2. **Unsupported Chain** * **Status Code**: `400 Bad Request` * **Response Body**: ```json { "status": false, "msg": "Unsupported chain ID" } ``` 3. **Internal Server Error** * **Status Code**: `500 Internal Server Error` * **Response Body**: ```json { "status": false, "msg": "An unexpected error occurred." } ``` This documentation covers two endpoints used to retrieve trade history and DEX trades for a given token. The endpoints allow you to fetch historical and real-time data across various supported blockchain networks. #### Endpoints **1. Retrieve Token Trade History** **Endpoint:** `GET /inspection/token/:chain/:address/trade/history` This endpoint retrieves the trade history for a specific token in USD. **Parameters:** * **Path Parameters:** * `chain` (Number): The network chain ID (e.g., `1` for Ethereum, `900` for Solana Devnet, `800` for Solana Mainnet). * `address` (String): The token's smart contract address. * **Query Parameters:** * `start` (Number, optional): The start date in seconds since Unix epoch. Defaults to 24 hours before the current time. * `end` (Number, optional): The end date in seconds since Unix epoch. Defaults to the current time. * `sort` (String, optional): The sorting order of the results (`asc` or `desc`). Defaults to `desc`. * `limit` (Number, optional): The maximum number of results to return. Defaults to `300`. * `page` (Number, optional): The page number for paginated results. Defaults to `1`. * `time` (String, optional): The nature of the results (`realtime` or `history`). Defaults to `realtime`. **Response:** Returns a JSON object containing the following: * **status** (Boolean): Indicates the success or failure of the request. * **data** (Object): * **trades** (Object): * `buy` (Array): A list of buy trades. * `sell` (Array): A list of sell trades. * **buyTotal** (Object): * `usd` (Number): The total USD value of buy trades. * `amount` (Number): The total amount of tokens bought. * **sellTotal** (Object): * `usd` (Number): The total USD value of sell trades. * `amount` (Number): The total amount of tokens sold. **Example Request:** ```bash GET /inspection/token/1/0x1234abcd.../trade/history?start=1625097600&end=1625184000&sort=asc&limit=100&page=1&time=history ``` **Example Response:** ```json { "status": true, "data": { "trades": { "buy": [ { "usd": "1000.00", "amount": "0.5", "buyer": "0xabc...", "seller": "0xdef...", "name": "TokenName", "symbol": "TKN", "date": "1625097600", "hash": "0x123...", "caller": "0xabc...", "contract": "0x456...", "protocol": "Uniswap" } ], "sell": [] }, "buyTotal": { "usd": 1000, "amount": 0.5 }, "sellTotal": { "usd": 0, "amount": 0 } } } ``` **2. Retrieve DEX Trades by Token** **Endpoint:** `GET /inspection/token/:chain/:address/dex/trades` This endpoint retrieves decentralized exchange (DEX) trades for a given token, with details on both buy and sell transactions. **Parameters:** * **Path Parameters:** * `chain` (Number): The network chain ID (e.g., `1` for Ethereum, `900` for Solana Devnet, `800` for Solana Mainnet). * `address` (String): The token's smart contract address. * **Query Parameters:** * `start` (Number, optional): The start date in seconds since Unix epoch. Defaults to 24 hours before the current time. * `end` (Number, optional): The end date in seconds since Unix epoch. Defaults to the current time. * `sort` (String, optional): The sorting order of the results (`asc` or `desc`). Defaults to `desc`. * `limit` (Number, optional): The maximum number of results to return. Defaults to `300`. * `page` (Number, optional): The page number for paginated results. Defaults to `1`. * `time` (String, optional): The nature of the results (`realtime` or `history`). Defaults to `realtime`. **Response:** Returns a JSON object containing the following: * **status** (Boolean): Indicates the success or failure of the request. * **data** (Object): * **trades** (Array): A list of trades including the following details: * `action` (String): Indicates if the trade was a `BUY` or `SELL`. * `buyUsd` (Number): The USD value of the bought tokens. * `buyAmount` (Number): The amount of tokens bought. * `buyToken` (Object): * `name` (String): The name of the bought token. * `symbol` (String): The symbol of the bought token. * `address` (String): The contract address of the bought token. * `sellUsd` (Number): The USD value of the sold tokens. * `sellAmount` (Number): The amount of tokens sold. * `sellToken` (Object): * `name` (String): The name of the sold token. * `symbol` (String): The symbol of the sold token. * `address` (String): The contract address of the sold token. * `buyer` (String): The address of the buyer. * `seller` (String): The address of the seller. * `date` (String): The date of the transaction. * `hash` (String): The transaction hash. * `from` (String): The address from which the transaction originated. * `contract` (String): The contract address involved in the transaction. * `protocol` (String): The protocol used for the trade (e.g., Uniswap). **Example Request:** ```bash GET /inspection/token/1/0x1234abcd.../dex/trades?start=1625097600&end=1625184000&sort=asc&limit=100&page=1&time=history ``` **Example Response:** ```json { "status": true, "data": { "trades": [ { "action": "BUY", "buyUsd": "1000.00", "buyAmount": "0.5", "buyToken": { "name": "TokenName", "symbol": "TKN", "address": "0x123..." }, "sellUsd": "1000.00", "sellAmount": "0.5", "sellToken": { "name": "TokenName", "symbol": "TKN", "address": "0x456..." }, "buyer": "0xabc...", "seller": "0xdef...", "date": "1625097600", "hash": "0x789...", "from": "0xabc...", "contract": "0x456...", "protocol": "Uniswap" } ] } } ``` #### Supported Networks * Ethereum Mainnet (Chain ID: 1) * Binance Smart Chain (Chain ID: 56) * Solana Devnet (Chain ID: 900) * Solana Mainnet (Chain ID: 800) * Arbitrum (Chain ID: 42161) * Base (Chain ID: 8453) #### Error Responses * **400 Bad Request:** When required parameters are missing or invalid. * **500 Internal Server Error:** When an unexpected error occurs. #### Notes * The default time range for both endpoints is set to the last 24 hours if no `start` and `end` parameters are provided. * The `limit` parameter is capped at 300 to prevent excessive data load. * The `time` parameter allows switching between real-time and archived data, providing flexibility in querying recent or historical trades. #### Retrieve Token Transfer History This API endpoint allows users to retrieve the transfer history of a specific token on supported blockchain networks. The transfer history includes details such as the sender, receiver, amount, and transaction metadata. **Endpoint** `GET /inspection/token/:chain/:address/transfers` **Description** This endpoint retrieves the transfer history for a specified token on a given blockchain. The history includes details of transactions involving the token, including transfers to and from other addresses. **Parameters** **Path Parameters:** * `chain` (Number): The blockchain network ID where the token resides. Default is `1` (Ethereum). Supported chains include: * `1`: Ethereum * `56`: Binance Smart Chain * `800`: Solana Devnet * `900`: Solana Mainnet * `42161`: Arbitrum * `8453`: Base * `address` (String): The address of the token or wallet whose transfer history is to be retrieved. **Query Parameters:** * `start` (Number): The start date filter in seconds since epoch (timestamp). Defaults to `0` (start from the beginning). * `end` (Number): The end date filter in seconds since epoch (timestamp). Defaults to the current timestamp. * `sort` (String): Sort order of the results. Accepts `asc` (ascending) or `desc` (descending). Defaults to `desc`. * `limit` (Number): The maximum number of results to return. Defaults to `300`. The maximum allowed value is `300`. * `page` (Number): The page number for paginated results. Defaults to `1`. * `time` (String): Specifies the nature of the results. Accepts `realtime` (default) for current data or `history` for archived data. **Response** * **Status Code:** `200 OK` * **Response Body:** JSON object containing the transfer history data. **Sample Response:** ```json { "status": true, "data": { "transfers": [ { "action": "TRANSFER", "amount": "123.45", "name": "TokenName", "symbol": "TKN", "address": "0x1234...abcd", "sender": "0xabcd...1234", "receiver": "0xefgh...5678", "date": "2024-08-20T14:48:00Z", "hash": "0x9a8b...cdef" }, ... ] } } ``` **Error Responses** * **400 Bad Request:** Returned if required parameters are missing or invalid. * **500 Internal Server Error:** Returned if there is an issue processing the request on the server. **Example Request** ``` GET /inspection/token/1/0x1234abcd5678efgh9012ijkl3456mnop/transfers?start=1622505600&end=1625097600&sort=asc&limit=100&page=1&time=realtime ``` This example request fetches the transfer history for the token at address `0x1234abcd5678efgh9012ijkl3456mnop` on the Ethereum network, for transactions occurring between `June 1, 2021` and `July 1, 2021`, sorted in ascending order, with a limit of 100 results per page. **Notes** * Ensure the chain parameter matches a supported network to avoid errors. * The default behavior provides a maximum of 300 results, but this can be adjusted by modifying the `limit` parameter.