Request Syntax

Method: GET and POST

Endpoint: https://api.syve.ai/v1/topk-api

Introduction

The TopK API is used for the fast retrieval of the top records for one or more groups of records.

Use `POST` for large requests

You can make POST as well as GET requests using the TopK API. GET requests have a 2048 character limit for the URL. For requests that exceed this limit use POST.

`GET` request syntax

For GET requests the request parameters are provided as URL query parameters.

https://api.syve.ai/v1/topk-api/<table_name>?groupby=<groupby>&eq=<eq>&sortby=<sortby>&order=<order>&size=<size>

Details on each query parameter is provided in the "request parameters" section. Details on table_name is provided in the "valid values for table_name" section.

`POST` request syntax

For POST requests the request parameters are provided in the body as JSON.

curl --location --request POST 'https://api.syve.ai/v1/topk-api/<table_name>' \
--header 'Content-Type: application/json' \
--data '{
    "groupby": <groupby>,
    "eq": <eq>,
    "sortby": <sortby>,
    "order": <order>,
    "size": <size>
}'

Details on each query parameter is provided in the "request parameters" section. Details on table_name is provided in the "valid values for table_name" section.

Valid values for `<table_name>`

Name	Reference
Transactions	`transactions`
Blocks	`blocks`
Logs	`logs`
ERC20 Transfers	`erc20`
ERC721 Transfers	`erc721`
DEX Trades	`dex-trades`
Token Balances	`token-balances`

The TopK API can be used on all our tables. For more information about each table click here.

Request Parameters

Name	Type	Description
`groupby`	`string`	The field in `table_name` you want to group by.
`eq`	`string` or `list`	The exactly values of the provided field you want to group by.
`sortby`	`string`	The field in `table_name` to rank records by.
`order`	`string`	The order in which to rank records by. Possible values: `desc` and `asc`. The default is `desc`.
`size`	`integer`	The number of top records to return. The default is 1.

Example

The example below fetches the first transfers made by wallets 0xb1e66855fd67f6e85f0f0fa38cd6fbabdf00923c and 0x3416cf6c708da44db2624d63ea0aaef7113527c6.

GET request

Request: https://api.syve.ai/v1/topk-api/erc20?groupby=from_address&eq=0xb1e66855fd67f6e85f0f0fa38cd6fbabdf00923c,0x3416cf6c708da44db2624d63ea0aaef7113527c6&sortby=timestamp&order=asc&size=1

POST request

curl --location --request POST 'https://api.syve.ai/v1/topk-api/erc20' \
--header 'Content-Type: application/json' \
--data '{
    "groupby": "from_address",
    "eq": [
        "0xb1e66855fd67f6e85f0f0fa38cd6fbabdf00923c",
        "0x3416cf6c708da44db2624d63ea0aaef7113527c6"
    ],
    "sortby": "timestamp",
    "order": "asc",
    "size": 1
}'

Response

{
    "0x3416cf6c708da44db2624d63ea0aaef7113527c6": [
        {
            "record_index": 5445608000000046,
            "transaction_hash": "0xf336a5122a084eb613dc23ecf5a98ba7e4df22be9a314d13f7e3060bd9747d37",
            "transaction_index": 59,
            "block_number": 13614020,
            "timestamp": 1636893273,
            "from_address": "0x3416cf6c708da44db2624d63ea0aaef7113527c6",
            "to_address": "0xce745843f987eaa5825f3d6523b97a965e2fc5d2",
            "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "token_symbol": "USDC",
            "token_name": "USD Coin",
            "log_index": 46,
            "value_base": "2020202867",
            "value_token": 2020.202867,
            "value_usd": 2006.3515321723712
        }
    ],
    "0xb1e66855fd67f6e85f0f0fa38cd6fbabdf00923c": [
        {
            "record_index": 7247878800000245,
            "transaction_hash": "0xfff96895e448ce2580c1fc195fb7b384279936313a06bf6a4943ae19f4b43953",
            "transaction_index": 214,
            "block_number": 18119697,
            "timestamp": 1694515019,
            "from_address": "0xb1e66855fd67f6e85f0f0fa38cd6fbabdf00923c",
            "to_address": "0xe2085d07dea91fa1fb510904c44cdbd7bfc114ef",
            "token_address": "0x2b591e99afe9f32eaa6214f7b7629768c40eeb39",
            "token_symbol": "HEX",
            "token_name": "HEX",
            "log_index": 245,
            "value_base": "10088328062453",
            "value_token": 100883.28062453,
            "value_usd": 340.8271385133324
        }
    ]
}

Introduction

Use POST for large requests

GET request syntax