Skip to main content

Prize API

The Prize API is an easy way to access the PoolTogether V4 prize data. For a detailed description of how the prizes are calculated see here.

This data contains:

  1. Which addresses won prizes for each draw across networks
  2. How much each address won for each draw
  3. Which lucky pick won for each users prize

This data can be accessed via:

  • Hosted API
  • Locally

This data can be reproduced by following the instructions here.

Usage

The Prize data is first catagorized by network, specifically chainId.

The data is then catagorized by Prize Distributor address. This is the contract that distributes the prizes associated with a Ticket on a network. This is because a Ticket may have multiple Prize Distributors.

NetworkPrize Distributor
mainnet0xb9a179dca5a7bf5f8b9e088437b3a85ebb495efe
polygon0x8141bcfbcee654c5de17c4e2b2af26b67f9b9056
avalanche0x83332f908f403ce795d90f677ce3f382fe73f3d1

Finally the data is sorted by drawId, where drawId is unique and sequentially increasing over time.

NOTE: These addresses must be lower case.

NOTE: The Prize data does not reduce the prizes claimable according to the maxPicksPerUser protocol limit.

Data Structure

The Prize data is expressed as follows:

[
...
{
address: "0x01a0f8f364c2fec07cfcdebd2980da3f950d0410",
pick: "20165",
tier: 5,
amount: "9999999",
},
{
address: "0x020bf6c3166dcca9f5efd5ba14652d62c6c5d422",
pick: "2018",
tier: 3,
amount: "99999999",
},
...
];
FieldDescription
addressaddress of the user
pickwhich pick won this prize
tierthe prize tier of this prize
amountthe prize amount

Hosted API

The following section describes how to use the hosted API at https://api.pooltogether.com/prizes

All Prizes per Draw

This API endpoint serves a JSON file with all the winners for that particular drawId.

HTTP GET https://api.pooltogether.com/prizes/:chainId/:prizeDistributorAddress/draw/:drawId/prizes.json

FieldDescriptionExample/Description
chainIdthe chainId of the network1 for Ethereum mainnet, 137 for Polygon, 43114 for Avalanche
prizeDistributorAddressaddress of the prize distributorthe prize distributor address associated with this prize
drawIdthe integer drawIddrawId's are unique and sequential over time

All Prizes per Address for a Draw

This API endpoint serves a JSON file for an individual address per draw, enabling more granular usage/analysis.

HTTP GET https://api.pooltogether.com/prizes/:chainId/:prizeDistributorAddress/draw/:drawId/:address.json

FieldDescriptionExample/Description
chainIdthe chainId of the network1 for Ethereum mainnet, 137 for Polygon, 43114 for Avalanche
prizeDistributorAddressaddress of the prize distributorthe prize distributor associated with this prize
drawIdthe integer drawIddrawId's are sequential over time
addressthe address of the userthis address must be lower case

The endpoint will return a 404 status if the address passed was not a winner for that draw.

Examples

For example, using Javascript and Fetch, getting the results for drawId 10 on Ethereum mainnet:

const draw10PrizesResult = await fetch(
`https://api.pooltogether.com/prizes/1/0xb9a179dca5a7bf5f8b9e088437b3a85ebb495efe/draw/10/prizes.json`
);
const draw10PrizesArray = await draw10PrizesResult.json();

Equivalently, drawId 10 on Avalanche:

const draw10PrizesResult = await fetch(
`https://api.pooltogether.com/prizes/43114/0x83332f908f403ce795d90f677ce3f382fe73f3d1/draw/10/prizes.json`
);
const draw10PrizesArray = await draw10PrizesResult.json();

If we wanted to get prizes for every user for drawId's 8 and 9 on Polygon we would make the following requests:

const urls = [
`https://api.pooltogether.com/prizes/137/0x8141bcfbcee654c5de17c4e2b2af26b67f9b9056/draw/8/prizes.json`,
`https://api.pooltogether.com/prizes/137/0x8141bcfbcee654c5de17c4e2b2af26b67f9b9056/draw/9/prizes.json`,
];

const prizes = await Promise.all(
urls.map(async (url) => {
const resp = await fetch(url);
return await resp.json();
})
);

Local Usage

The data served from this API can also be installed locally using yarn or npm. This method may be prefered for data analysis or similar purposes.

Example

In your package.json add:

  ...
"dependencies": {
...
"v4PrizesData": "git+https://github.com/pooltogether/v4-draw-results.git"
}
...

This data can then be imported into scripts for analysis using:

// all winners data for draw 2 on mainnet
import allWinnersDraw2 from "./node_modules/v4PrizesData/api/prizes/1/0xb9a179dca5a7bf5f8b9e088437b3a85ebb495efe/draw/2/prizes";