API endpoints

Endpoints:

API info
Tokens
Strategies
Censuses

API Info

GET `/info`

Show information about the API service.

📥 response:

{
    "supportedChains": [
        {
            "chainID": 5,
            "shortName": "gor",
            "name": "Goerli"
        },
        {
            "chainID": 137,
            "shortName": "matic",
            "name": "Polygon Mainnet"
        },
        {
            "chainID": 80001,
            "shortName": "maticmum",
            "name": "Mumbai"
        },
        {
            "chainID": 1,
            "shortName": "eth",
            "name": "Ethereum Mainnet"
        }
    ]
}

⚠️ errors:

HTTP Status	Message	Internal error
500	`error encoding API info`	5023

Tokens

GET `/tokens`

List of already added tokens.

Pagination URL params

URL key	Description	Example
`pageSize`	(optional) Defines the number of results per page. By default, `100`.	`?pageSize=2`
`nextCursor`	(optional) When is defined, it is used to get the page results, going forward. By default, `""`.	`?nextCursor=0x1234`
`prevCursor`	(optional) When is defined, it is used to get the page results, going backwards. By default, `""`.	`?prevCursor=0x1234`

The maximus default page size is 10, but if you provide a page size of -1, the endpoint will return all the results, and it does not require to be paginated.

📥 response:

{
    "tokens": [
        {
            "ID": "0x1324",
            "type": "erc20",
            "decimals": 18,
            "startBlock": 123456,
            "symbol": "$",
            "totalSupply": "21323",
            "name": "Amazing token",
            "synced": true|false,
            "defaultStrategy": 1,
            "tags": "testTag1,testTag2",
            "chainID": 1,
            "externalID": "",
            "chainAddress": "eth:0x1234",
            "iconURI": "http://...png"
        }
    ],
    "pagination": {
        "nextCursor": "",
        "prevCursor": "0x1234",
        "pageSize": 10
    }
}

If tags is empty, it will be ommited.

If externalID is empty, it will be ommited.

⚠️ errors:

HTTP Status	Message	Internal error
204	`no tokens found`	4007
400	`malformed pagination params`	4022
500	`error getting tokens information`	5005
500	`error encoding tokens`	5011

GET `/tokens/types`

List the supported token types.

📥 response:

{
    "supportedTypes": [
        "erc20", 
        "erc721", 
        "erc777", 
        "erc1155", 
        "nation3", 
        "wANT", 
        "poap"
    ]
}

⚠️ errors:

HTTP Status	Message	Internal error
500	`error encoding supported tokens types`	5012

POST `/tokens`

Creates a new token in the database to be scanned. It gets the token information from the provider associated to the token type defined. If the creation success the token will be scanned in the next scanner iteration. The scan process status can be checked getting the token information.

Important: When a token is created, the API also creates a simple strategy with just the holders of that token, which is assigned to it as defaultStrategy.

📤 request:

{
    "ID": "0x1234",
    "type": "erc20|erc721|erc777|erc1155|nation3|wANT|poap",
    "tags": "testTag1,testTag2",
    "chainID": 1,
    "externalID": "" // id for external holders providers
}

tags attribute is optional.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed token information`	4000
409	`token already created`	4009
400	`chain ID provided not supported`	4013
500	`the token cannot be created`	5000
500	`error getting token information`	5004
500	`error initialising web3 client`	5019

GET `/tokens/{tokenID}?chainID={chainID}&externalID={externalID}`

Returns the information about the token referenced by the provided ID and chain ID, the external ID is optional.

chainID URL parameter is mandatory.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

📥 response:

{
    "ID": "0x1324",
    "type": "erc20",
    "size": 120,
    "decimals": 18,
    "startBlock": 123456,
    "symbol": "$",
    "totalSupply": "21323",
    "name": "Amazing token",
    "status": {
        "atBlock": 12345,
        "synced": true|false,
        "progress": 87
    },
    "defaultStrategy": 1,
    "tags": "testTag1,testTag2",
    "chainID": 1,
    "externalID": "",
    "chainAddress": "eth:0x1234",
    "iconURI": "http://...png"
}

If tags is empty, it will be ommited.

If externalID is empty, it will be ommited.

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed token information`	4001
400	`malformed chain ID`	4018
404	`no token found`	4003
500	`error getting token information`	5004
500	`error encoding token`	5010
500	`chain ID provided not supported`	5013
500	`error initialising web3 client`	5019
500	`error getting number of token holders`	5020
500	`error getting last block number from web3 endpoint`	5021

GET `/tokens/{tokenID}/holders/{holderID}?chainID={chainID}&externalID={externalID}`

Returns the holder balance if the holder ID is already registered in the database as a holder of the token ID and chain ID provided, the external ID is optional.

chainID URL parameter is mandatory.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

📥 response:

{
    "balance": "1234567890"
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed token information`	4001
400	`malformed chain ID`	4018
404	`no token found`	4003
404	`token holder not found for the token provided`	4023
500	`error getting token holders`	5006

Strategies

GET `/strategies`

Returns the ID's list of the strategies registered.

Pagination URL params

URL key	Description	Example
`pageSize`	(optional) Defines the number of results per page. By default, `100`.	`?pageSize=2`
`nextCursor`	(optional) When is defined, it is used to get the page results, going forward. By default, `""`.	`?nextCursor=3`
`prevCursor`	(optional) When is defined, it is used to get the page results, going backwards. By default, `""`.	`?prevCursor=1`

The maximus default page size is 10, but if you provide a page size of -1, the endpoint will return all the results, and it does not require to be paginated

📥 response:

{
    "strategies": [
        {
            "ID": 1,
            "alias": "default MON strategy",
            "predicate": "MON",
            "uri": "ipfs://...",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                }
            }
        },
        {
            "ID": 2,
            "alias": "default ANT strategy",
            "predicate": "ANT",
            "uri": "ipfs://...",
            "tokens": {
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234" 
                }
            }
        },
        {
            "ID": 3,
            "alias": "default USDC strategy",
            "predicate": "USDC",
            "uri": "ipfs://...",
            "tokens": {
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        },
        {
            "ID": 4,
            "alias": "strategy_alias",
            "predicate": "MON AND (ANT OR USDC)",
            "uri": "ipfs://...",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                },
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234",
                    "minBalance": "1"
                },
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        }
    ],
    "pagination": {
        "nextCursor": "",
        "prevCursor": "1",
        "pageSize": 10
    }
}

⚠️ errors:

HTTP Status	Message	Internal error
204	`-`	4008
400	`malformed pagination params`	4022
500	`error getting strategies information`	5008
500	`error encoding strategies`	5016

POST `/strategies`

Stores a new strategy based on the defined combination of tokens provided, these tokens must be registered previously.

📤 request:

    {
        "alias": "test_strategy",
        "predicate": "(wANT OR ANT) AND USDC",
        "tokens": {
            "wANT": {
                "ID": "0x1324",
                "chainID": 1,
                "minBalance": "10000"
            },
            "ANT": {
                "ID": "0x1324",
                "chainID": 5,
            },
            "USDC": {
                "ID": "0x1324",
                "chainID": 1,
                "minBalance": "50"
            },
        }
    }

📥 response:

{
    "strategyID": 1
}

⚠️ errors:

HTTP Status	Message	Internal error
404	`no token found`	4003
400	`malformed strategy provided`	4014
400	`the predicate provided is not valid`	4015
400	`the predicate includes tokens that are not included in the request`	4016
500	`error encoding strategy info`	5015
500	`error creating strategy`	5025

POST `/strategies/import/{cid}`

Imports a strategy from IPFS downloading it with the cid provided in background. The strategy import will fail if the strategy tokens are not previously created in the database.

📥 response:

{
    "queueID": "0123456789abcdef0123456789abcdef01234567"
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed strategy provided`	4014
500	`error encoding strategy info`	5015

GET `/strategies/import/queue/{queueID}`

Returns the information of the strategy that are in the creation queue.

📥 response:

{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "strategy": { /* <same_get_strategy_response> */ }
}

⚠️ errors:

HTTP Status	Message	Internal error
404	`strategy not found`	4006
400	`malformed queue ID`	4011
500	`error getting strategy information`	5009
500	`error encoding queue item`	5022

⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

GET `/strategies/{strategyID}`

Returns the information of the strategy related to the provided ID.

📥 response:

{
    "ID": 4,
    "alias": "strategy_alias",
    "predicate": "MON AND (ANT OR USDC)",
    "uri": "ipfs://...",
    "tokens": {
        "MON": {
            "ID": "0x1234",
            "chainID": 5,
            "chainAddress": "gor:0x1234",
            "externalID": "mon_id_on_external_holder_provider"
        },
        "ANT": {
            "ID": "0x1234",
            "chainID": 1,
            "chainAddress": "eth:0x1234",
            "minBalance": "1"
        },
        "USDC": {
            "ID": "0x1234",
            "chainID": 1,
            "chainAddress": "eth:0x1234"
        }
    }
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed strategy ID, it must be an integer`	4002
404	`no strategy found with the ID provided`	4005
500	`error getting tokens information`	5005
500	`error getting strategy information`	5007
500	`error encoding strategy info`	5015

GET `/strategies/{strategyID}/estimation?anonymous={true|false}`

Enqueue the estimation of size and time (in milliseconds) to create the census generated for the provided strategy. It also calculates the accuracy of the resulting census, it could be different to 100% if the census will be anonymous.

📥 response:

{
    "queueID": "0123456789abcdef0123456789abcdef01234567",
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed strategy ID, it must be an integer`	4002
500	`error encoding strategy info`	5015

GET `/strategies/{strategyID}/estimation/queue/{queueID}`

Returns the estimation of size and time (in milliseconds) to create the census generated for the strategy related to the queue ID.

📥 response:

{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "estimation": {
        "size": 15000,
        "timeToCreateCensus": 10900,
        "accuracy": 100.0,
    }
}

⚠️ errors:

HTTP Status	Message	Internal error
404	`no strategy found with the ID provided`	4005
400	`malformed queue ID`	4020
500	`error encoding queue item`	5022

⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

HTTP Status	Message	Internal error
404	`no strategy found with the ID provided`	4005
400	`the predicate provided is not valid`	4015
204	`strategy has not registered holders`	4017
500	`error getting strategy information`	5007
500	`error evaluating strategy predicate`	5026

GET `/strategies/{strategyID}/holders`

Returns the list of holders with their balances for a strategy. This endpoint only works with single token strategies like default ones.

Pagination URL params

URL key	Description	Example
`pageSize`	(optional) Defines the number of results per page. By default, `1000`.	`?pageSize=2`
`nextCursor`	(optional) When is defined, it is used to get the page results, going forward. By default, `""`.	`?nextCursor=0x1234`
`prevCursor`	(optional) When is defined, it is used to get the page results, going backwards. By default, `""`.	`?prevCursor=0x1234`

📥 response:

{
    "holders": {
        "0x1": "1",
        "0x2": "2",
        "0x3": "3",
        "0x4": "4",
        "0x...": "1000",
    },
    "pagination": {
        "nextCursor": "0x5",
        "prevCursor": "0x1",
        "pageSize": 5
    }
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed strategy ID, it must be an integer`	4002
404	`no token holders found`	4004
404	`no strategy found with the ID provided`	4005
400	`malformed pagination params`	4022
500	`error encoding token holders`	5013
500	`error getting strategy holders`	5030

GET `/strategies/token/{tokenID}?chainID={chainID}&externalID={externalID}`

Returns strategies registered that includes the token provided for the chain also provided, the external token id is an optional parameter.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

📥 response:

{
    "strategies": [
        {
            "ID": 1,
            "alias": "default MON strategy",
            "predicate": "MON",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234"
                }
            }
        },
        {
            "ID": 4,
            "alias": "strategy_alias",
            "predicate": "MON AND (ANT OR USDC)",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                },
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234",
                    "minBalance": "1"
                },
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        }
    ]
}

⚠️ errors:

HTTP Status	Message	Internal error
204	`-`	4008
500	`error getting strategies information`	5008
500	`error encoding strategies`	5016

POST `/strategies/predicate/validate`

Returns if the provided strategy predicate is valid and well-formatted. If the predicate is valid the handler returns a parsed version of the predicate as a JSON.

📤 request:

{
    "predicate": "DAI AND (ANT OR ETH)"
}

📥 response:

{
    "result": {
        "childs": {
            "operator": "AND",
            "tokens": [
                {
                    "literal": "DAI"
                },
                {
                    "childs": {
                        "operator": "OR",
                        "tokens": [
                            {
                                "literal": "ANT"
                            },
                            {
                                "literal": "ETH"
                            }
                        ]
                    }
                }
            ]
        }
    }
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed strategy provided`	4014
400	`the predicate provided is not valid`	4015
500	`error encoding validated strategy predicate`	5024

GET `/strategies/predicate/operators`

Returns the list of supported operators to build strategy predicates.

📥 response:

{
    "operators": [
        {
            "description": "logical operator that returns the common token holders between symbols with fixed balance to 1",
            "tag": "AND"
        },
        {
            "description": "logical operator that returns the token holders of both symbols with fixed balance to 1",
            "tag": "OR"
        }
    ]
}

⚠️ errors:

HTTP Status	Message	Internal error
500	`error encoding supported strategy predicate operators`	5027

Censuses

POST `/censuses`

Request the creation of a new census with the strategy provided and returns the census ID.

📤 request:

{
    "strategyID": 1,
    "anonymous": false
}

📥 response:

{
    "queueID": "0123456789abcdef0123456789abcdef01234567"
}

⚠️ errors :

HTTP Status	Message	Internal error
400	`malformed strategy ID, it must be an integer`	4002
500	`error encoding census`	5017

GET `/censuses/{censusID}`

Returns the information of the snapshots related to the provided ID.

📥 response:

{ 
    "ID": 2,
    "strategyID": 1,
    "merkleRoot": "e3cb8941e25dcdb36fc21acbe5f6c5a42e0d4f89839ae94952f0ebbd9acd04ac",
    "uri": "ipfs://Qma....",
    "size": 1000,
    "weight": "200000000000000000000",
    "anonymous": true,
    "accuracy": 100.0
}

⚠️ errors:

HTTP Status	Message	Internal error
400	`malformed census ID, it must be a integer`	4001
404	`census not found`	4006
500	`error getting census information`	5009
500	`error encoding census`	5017

GET `/censuses/queue/{queueID}`

Returns the information of the census that are in the creation queue.

📥 response:

{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "census": { /* <same_get_census_response> */ }
}

⚠️ errors:

HTTP Status	Message	Internal error
404	`census not found`	4006
400	`malformed queue ID`	4011
500	`error getting census information`	5009
500	`error encoding queue item`	5022

⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

HTTP Status	Message	Internal error
404	`no token holders found`	4004
404	`no strategy found with the ID provided`	4005
400	`no tokens found for the strategy provided`	4010
409	`census already exists`	4012
400	`the predicate provided is not valid`	4015
204	`strategy has not registered holders`	4017
500	`error creating the census tree on the census database`	5001
500	`error evaluating strategy predicate`	5026

GET `/censuses/strategy/{strategyID}`

Returns a list of censuses previously created for the strategy provided.

📥 response:

{
    "censuses": [ 
        { 
            "ID": 1,
            "strategyID": 1,
            "merkleRoot": "e3cb8941e25dcdb36fc21acbe5f6c5a42e0d4f89839ae94952f0ebbd9acd04ac",
            "uri": "ipfs://Qma....",
            "size": 1000,
            "weight": "200000000000000000000",
            "anonymous": true,
            "accuracy": 100.0
        }
    ]
}

⚠️ errors:

HTTP Status	Message	Internal error
204	`-`	4007
400	`malformed census ID, it must be a integer`	4001
404	`census not found`	4006
500	`error getting census information`	5009
500	`error encoding censuses`	5018

# README

API endpoints

API Info

GET /info

Tokens

GET /tokens

GET /tokens/types

POST /tokens

GET /tokens/{tokenID}?chainID={chainID}&externalID={externalID}

GET /tokens/{tokenID}/holders/{holderID}?chainID={chainID}&externalID={externalID}

Strategies

GET /strategies

POST /strategies

POST /strategies/import/{cid}

GET /strategies/import/queue/{queueID}

GET /strategies/{strategyID}

GET /strategies/{strategyID}/estimation?anonymous={true|false}

GET /strategies/{strategyID}/estimation/queue/{queueID}

GET /strategies/{strategyID}/holders

GET /strategies/token/{tokenID}?chainID={chainID}&externalID={externalID}

POST /strategies/predicate/validate

GET /strategies/predicate/operators

Censuses

POST /censuses

GET /censuses/{censusID}

GET /censuses/queue/{queueID}

GET /censuses/strategy/{strategyID}

GET `/info`

GET `/tokens`

GET `/tokens/types`

POST `/tokens`

GET `/tokens/{tokenID}?chainID={chainID}&externalID={externalID}`

GET `/tokens/{tokenID}/holders/{holderID}?chainID={chainID}&externalID={externalID}`

GET `/strategies`

POST `/strategies`

POST `/strategies/import/{cid}`

GET `/strategies/import/queue/{queueID}`

GET `/strategies/{strategyID}`

GET `/strategies/{strategyID}/estimation?anonymous={true|false}`

GET `/strategies/{strategyID}/estimation/queue/{queueID}`

GET `/strategies/{strategyID}/holders`

GET `/strategies/token/{tokenID}?chainID={chainID}&externalID={externalID}`

POST `/strategies/predicate/validate`

GET `/strategies/predicate/operators`

POST `/censuses`

GET `/censuses/{censusID}`

GET `/censuses/queue/{queueID}`

GET `/censuses/strategy/{strategyID}`