Authentication

The Dune API relies on API keys for authentication. Your API key grants access and determines billing details for private queries, so safeguard it diligently!

Generate an API key

In order to generate a new API key, go to settings -> API -> create new API key.

• Dune has two types of account: user account and team account. A team can have many users. A user can join many teams.
• Each user or team account has its own context. Queries created under a team account can only be managed within the team account context.
• An API key belongs to a specific context, and is either associated with a user account or a team account.
• New: Scoped API keys can now be created to allow access only to specific endpoints. See the section below on “Scope of a Key.”

Create key for user account

Create key for team account

Never share your secret API keys in public repositories or other accessible areas.

Permissions

When creating an API key, you can now choose between two permission levels to control which endpoints the key can access:

• All endpoints: This option grants full access to all API endpoints, including Developer APIs, executions, results, queries, tables, and materialized views. This is the default setting.
• Only Developer APIs: Limits access to only Dune’s real-time APIs, such as the Tokens API and Balances API.

You can select the appropriate level of access when creating a new API key in the settings under API -> Create API key.

Context of a key

As mentioned above, a team API key only has access to team account resources and not user account resources. This can be especially relevant when you use Query endpoints.

Authentication & making API calls

You can authenticate either with the API header or with query parameter to start making API calls. We illustrate below with execute query endpoint as an example.

Header Authentication

To authenticate via the API header, include an x-dune-api-key property in your request header.

cURL (bash)

curl -X POST -H x-dune-api-key:{{api_key}} "https://api.dune.com/api/v1/query/{{query_id}}/execute"

Python

import requests

url = "https://api.dune.com/api/v1/query/{{query_id}}/execute"

headers = {"X-DUNE-API-KEY": "<x-dune-api-key>"}

response = requests.request("POST", url, headers=headers)

print(response.text)

JavaScript

const options = {method: 'POST', headers: {'X-DUNE-API-KEY': '<x-dune-api-key>'}};

fetch('https://api.dune.com/api/v1/query/{{query_id}}/execute', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));

Go

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.dune.com/api/v1/query/{{query_id}}/execute"

    req, _ := http.NewRequest("POST", url, nil)

    req.Header.Add("X-DUNE-API-KEY", "<x-dune-api-key>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.dune.com/api/v1/query/{{query_id}}/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
    "X-DUNE-API-KEY: <x-dune-api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>

Java

HttpResponse<String> response = Unirest.post("https://api.dune.com/api/v1/query/{{query_id}}/execute")
.header("X-DUNE-API-KEY", "<x-dune-api-key>")
.asString();

Query Parameter Authentication

Alternatively, use an api_key query parameter for authentication.

cURL (bash)

curl -X POST "https://api.dune.com/api/v1/query/{{query_id}}/execute?api_key={{api_key}}"

Python

import requests

url = "https://api.dune.com/api/v1/query/{{query_id}}/execute"

querystring = {"api_key": "<api_key>"}

response = requests.request("POST", url, params=querystring)

print(response.text)

JavaScript

const options = {
method: 'POST',
};

const apiKey = '<api_key>';
const queryId = '{{query_id}}';
const url = `https://api.dune.com/api/v1/query/${queryId}/execute?api_key=${apiKey}`;

fetch(url, options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));

Go

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://api.dune.com/api/v1/query/{{query_id}}/execute?api_key=<api_key>"

    req, _ := http.NewRequest("POST", url, nil)

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))
}

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.dune.com/api/v1/query/{{query_id}}/execute?api_key=<api_key>",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response;
}
?>

Java

HttpResponse<String> response = Unirest.post("https://api.dune.com/api/v1/query/{{query_id}}/execute?api_key=<api_key>")
.asString();