Quickstart

This quickstart shows how to get started with the Exorde API using common tools and languages like Postman, curl or Python.

Instructions

1. Sign up at developers.exorde.io to get 1000 free credits to discover the API. No credit card required. You can upgrade to a paid plan at any time.

2. Get your API key for your account and store it securely.

3. Make a test call using the examples provided below. These examples list last posts collected by Exorde's protocol.

   info

   Be sure to replace the API Key in sample code with your own.

   cURL

   curl \
       --url https://api.exorde.io/posts \
       --header "X-Exorde-Api-Version: v1" \
       --header "Accept: application/json" \
       --header "Authorization: Bearer <api-key>"

   Python

   import requests
   
   url = "https://api.exorde.io/posts"
   
   headers = {
     'Accept': 'application/json',
     'X-Exorde-Api-Version': 'v1',
     'Authorization': 'Bearer <api-key>'
   }
   
   response = requests.request("GET", url, headers=headers)
   
   print(response.text)

   Node.js

   const url = "https://api.exorde.io/posts";
   const headers = {
     Accept: "application/json",
     "X-Exorde-Api-Version": "v1",
     Authorization: "Bearer <api-key>",
   };
   
   fetch(url, { headers })
     .then((response) => response.json())
     .then((data) => console.log(data))
     .catch((error) => console.error(error));

Real use case example

Scenario

In this example, we will use the Exorde API to get the sentiment history of Avalanche (avax) for December 2023, with a daily granularity.

Topic selection

First, we need to get the topic id of Avalanche using the List topics endpoint:

curl \
    --url 'https://api.exorde.io/topics?name=avalanche' \
    --header "X-Exorde-Api-Version: v1" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer <api-key>"

This will return the list of topics matching the name avalanche:

{
  "items": [
    {
      "id": 248,
      "name": "Avalanche (avax)",
      "categories": [
        { "id": 9, "name": "Cryptocurrency" },
        { "id": 3, "name": "Investing" },
        { "id": 7, "name": "Technology" }
      ]
    },
    {
      "id": 3977,
      "name": "Bitcoin Avalanche Bridged (BTC.b)",
      "categories": [
        { "id": 1, "name": "Business" },
        { "id": 9, "name": "Cryptocurrency" },
        { "id": 6, "name": "Economy" },
        { "id": 12, "name": "Finance" },
        { "id": 7, "name": "Technology" }
      ]
    }
  ],
  "pagination": {
    "self": "https://api.exorde.io/topics?name=avalanch"
  },
  "status": {
    "cost": 1
  }
}

There are two topics matching the name avalanche. The first one is the one we are looking for. We'll use its id 248 in further requests to get the sentiment history.

info

As you can see, a name is not enough to identify a topic. Several topics can share the same name, for example "apple" can refer to the company or the fruit. That's why we must first search for a topic using its name and then use its id to get the related data.

This is a common pattern in the Exorde API. You can use the List topics endpoint to search for a topic using its name, and then use the topic id to get the related data. The topic selection is not automated because it requires human intelligence, it's a one time process that you can do manually when integrating the API in your application.

Sentiment history

Now that we have the topic id, we can get the sentiment history using the Get sentiment history endpoint:

curl \
    --url 'https://api.exorde.io/sentiment/history?startDate=2023-12-01T00:00:00.000Z&endDate=2024-01-01T00:00:00.000Z&interval=1440&topicId=248&limit=31' \
    --header "X-Exorde-Api-Version: v1" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer <api-key>"

In the request above, we ask for the sentiment history of Avalanche (topic id 248) for December 2023, with a daily granularity (interval 1440). The available query parameters are explained in the Get sentiment history endpoint documentation, here we use:

• startDate: the start date of the sentiment history, in UTC.
• endDate: the end date of the sentiment history, in UTC. Remember that the end date is exclusive, so we use 2024-01-01T00:00:00.000Z to get the sentiment history of December 2023.
• interval: the granularity of the sentiment history, in minutes. We use 1440 minutes, which is 24 hours, so we get a daily granularity.
• topicId: the topic id of Avalanche.
• limit: the maximum number of items to return. We use 31, so we get the sentiment history of the 31 days of December 2023.

The response contains the sentiment history of Avalanche for December 2023:

{
  "items": [
    {
      "percentagePositivePosts": 69.83695652173913,
      "percentageNegativePosts": 19.83695652173913,
      "percentageNeutralPosts": 10.326086956521738,
      "sentiment": 0.14391305434782609,
      "postsCount": 1840,
      "startDate": "2023-12-01T00:00:00.000Z",
      "endDate": "2023-12-02T00:00:00.000Z"
    },
    // ...
    {
      "percentagePositivePosts": 68.52057842046719,
      "percentageNegativePosts": 24.768261030774934,
      "percentageNeutralPosts": 6.711160548757879,
      "sentiment": 0.19344642195031517,
      "postsCount": 2697,
      "startDate": "2023-12-31T00:00:00.000Z",
      "endDate": "2024-01-01T00:00:00.000Z"
    }
  ],
  "requestedInterval": 1440,
  "pagination": {
    "next": "http://api.exorde.io/sentiment/history?startDate=2023-12-01T00:00:00.000Z&endDate=2024-01-01T00:00:00.000Z&interval=1440&topicId=248&limit=31&paginationCursor=eyJhZnRlciI6eyJzdGFydERhdGUiOiIyMDIzLTEyLTMxVDAwOjAwOjAwLjAwMFoiLCJlbmREYXRlIjoiMjAyNC0wMS0wMVQwMDowMDowMC4wMDBaIn19",
    "self": "http://api.exorde.io/sentiment/history?startDate=2023-12-01T00:00:00.000Z&endDate=2024-01-01T00:00:00.000Z&interval=1440&topicId=248&limit=31"
  },
  "status": { "cost": 5 }
}

The response contains the sentiment history of Avalanche for December 2023, with a daily granularity. The fields in the response are explained in the Get sentiment history endpoint documentation.

Congrats! You can now use the sentiment history in your application to display a chart of the sentiment of Avalanche for December 2023.

API usage tips

You can use the form in the API reference to build your requests and get an example of how to call the API using curl, python or Node.js.

The API uses internal IDs to identify topics because a topic can be renamed (eg. "Twitter" renamed "X") or several topics can share the same name (eg. "Apple" can refer to the company or the fruit). That's why you should always use the List topics endpoint to get the ID of the topic you are looking for.

Notes about the API response:

• API responses are json objects, with the application/json content type. You can download the OpenAPI specification to get the full API specification in json format.
• By default the API does not always return the full ressources representation. Only most importants fields are returned by default. You can ask for more fields, or even all fields using the query parameter additionalFields. You can see all available fields in the API reference. Fields that are always returned are marked as required in the response schema.

Discover the API using Postman

We provide an OpenAPI specification that can be imported in Postman to generate a Postman collection and discover the API:

1. Open Postman.
2. Click on Import.
3. Enter the following URL: https://docs.exorde.io/openapi.json.
4. Select Postman Collection as the import type.
5. Click on View Import Settings.
6. Set the following options:
   • Naming requests: Fallback
   • Set indent character: Space
   • Parameter generation: Example
   • Folder organization: Tags
   • Include auth info in example requests: Yes
   • Enable optional parameters: No
   • Keep implicit headers: No
   • Include deprecated properties: No
   • Always inherit authentication: Yes
7. Go back to the previous screen and click on Import.
8. Create an environment and add a variable named bearerToken with your API key as value.

The collection is now imported in Postman, it contains all the API endpoints and their respective documentation.

You can try the different endpoints. For example, to list the last posts collected by Exorde's protocol:

1. Click on the Posts > List posts endpoint.
2. Click on Send.

You should see the last posts collected by Exorde's protocol.

tip

Here are some tips to discover the API with Postman:

• You can browse the endpoints in the left sidebar, they follow the order of the API Reference.
• Each folder has a description of the endpoints it contains. You can click on the folder to see the description.
• Each endpoint is fully documented. You can show the documentation by clicking on the Documentation button in the right sidebar.
• For each endpoint, all possible parameters are also documented, you can easily check/uncheck them to try different requests.