Getting Started with Numerai’s New Tournament API

Update: Now that API tokens have been released, the authentication flow has changed. This post has been edited to reflect the new way.

Today, Numerai released a new API to interact with our tournament. For more about the scope and purpose of this API, check out our Master Plan. Here, I’m going to show you how to start using the API.

This API has exactly one endpoint: /. It supports GraphQL requests exclusively. The best way to get started with it is to just visit it: https://api-tournament.numer.ai. Explore, and see what you can discover.

Simple queries

Let’s say we want to get the date when each round was resolved. Here’s the request:

query simpleRoundsRequest {
  rounds {
    number
    resolveTime
  }
}

You can copy this into the GraphiQL interface and run it. Your result should look something like this:

Baby’s first query

You input the query on the left, press the triangular “go” button, and see the result in the center column. You can explore the docs on the right.

Let’s break this down line-by-line. We’re making a query (as opposed to a mutation), and we’re going to name it simpleRoundsRequest. If you’re only making a single query per request, you don’t have to give it a name.

rounds is one of the root queries that we can make. We then specify which fields we want the API to compute and return to us: number and resolveTime.

You can find all the queries and mutations you can run in the “Docs” sidebar. Each query or mutation returns an object of some type. In this case, the rounds query produces a list of objects of type Round. You can click “Round” to see which fields you can query. Some of these fields are scalars, like number and resolveTime. Others are complex, and you can specify exactly which parts of them you want. For example, consider this query:

query loglosses {
  rounds(number: 55) {
    leaderboard {
      username
      validationLogloss
      payment {
        usdAmount
      }
    }
  }
}

Here, we request the username and validation logloss of all submissions in round 55, as well as how much USD they received (if they won any).

Authentication

Let’s look at one more query:

query user {
  user {
    availableNmr
    nmrWithdrawals {
      value
      txHash
      status
    }
    stakeTxs {
      roundNumber
      txHash
      value
      confidence
    }
  }
}

This should produce your current NMR balance, a list of your NMR withdrawals (with value, transaction hash, and whether it’s been confirmed on the blockchain), and a list of your stakes.

If you try to run this query, though, it’ll complain that you must be authenticated. You authenticate with an API token, which is a combination of a public ID and a secret key. You can create these by logging in to the website, going to the “Accounts” tab, and selecting “Custom API Keys”.

Each key has a set of permissions, called scopes. Choose which ones you need, and generate the key. The public ID will be shown in the page, and the secret key will appear in the banner at the bottom. We’ll refer to these below as PUBLIC_ID and SECRET_KEY.

Back in the GraphiQL interface, click the “Add” button next to the “Headers” heading in the top panel. Add a header with name Authorization and value Token PUBLIC_ID$SECRET_KEY. Press “OK”, and try again to run the user query from before.

Making requests outside the GraphiQL interface

The GraphiQL interface is great for exploring, but the API’s real power is that programs can interact with it. There exist GraphQL client libraries and frameworks, or you can make HTTP requests directly.

If you make HTTP requests directly, your requests should have at least two headers: Content-Type: application/json and Accept: application/json. If you’re unexpectedly receiving HTML from the API, you probably forgot the Accept header, so it’s trying to serve you the GraphiQL interface. If you wish to be authenticated, you need to pass the API token you generated in another header: Authorization: Token PUBLIC_ID$SECRET_KEY.

For example, here’s a curl request to find out when the current round will resolve:

$ curl https://api-tournament.numer.ai \
    -H 'Content-type: application/json' \
    -H 'Accept: application/json' \
    -d '{"query": "{rounds(number: 80) { resolveTime }}"}'
{"data":{"rounds":[{"resolveTime":"2017-11-28T15:00:00Z"}]}}

That should be enough to get you started. Drop by our chat rooms or forum to ask questions about the new API or show off what you’re building!