Inspection API

This page discuss the integration APIs

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:

{
  "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:

    {
  "status": false,
  "msg": "Missing parameters. Expecting: address"
}

  2. Unsupported Chain

    • Status Code: 400 Bad Request

    • Response Body:

    {
  "status": false,
  "msg": "Unsupported chain ID"
}

  3. Internal Server Error

    • Status Code: 500 Internal Server Error

    • Response Body:

    {
  "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:

{
  "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:

    {
  "status": false,
  "msg": "Missing parameters. Expecting: address"
}

  2. Unsupported Chain

    • Status Code: 400 Bad Request

    • Response Body:

    {
  "status": false,
  "msg": "Unsupported chain ID"
}

  3. Internal Server Error

    • Status Code: 500 Internal Server Error

    • Response Body:

    {
  "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:

GET /inspection/token/1/0x1234abcd.../trade/history?start=1625097600&end=1625184000&sort=asc&limit=100&page=1&time=history

Example Response:

{
  "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:

GET /inspection/token/1/0x1234abcd.../dex/trades?start=1625097600&end=1625184000&sort=asc&limit=100&page=1&time=history

Example Response:

{
  "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:

{
  "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.

PreviousSmart Contract API

Last updated