Skip to main content

Making your first request

Now that you know the basics of Basement and GraphQL, it's time to send some requests.

Endpoint​

Basement’s GraphQL endpoint is hosted at https://api.basement.dev/v2/graphql

There are many valid ways of making requests to a GraphQL API. You can choose one of the existing client GraphQL libraries in your language of choice, or head over to the official documentation to roll your own.

info

Explore and learn about Basement’s API endpoints using the 🌐 GraphQL Playground

Authentication​

Queries to Basement’s API are free for 30 requests per minute without an API key. Once this limit is exceeded an API key is necessary. Head over to the Pricing page to find a plan that fits your use-case.

Include your API key as a X-Basement-API-Key header on all API requests. Using Basement's SDK may simplify this process.

curl -X POST \
    https://api.basement.dev/v2/graphql \
    -H 'Content-Type: application/graphql' \
    -H 'X-Basement-API-Key: {key}' \
    -d '{your_query}'

Queries​

Queries start with one of the objects listed under Query, this is the schema’s entry-point for any query.

These queries can be seen as the equivalent of making a GET request in REST. The example shown lists the last 3 transactions included on-chain.

curl -X POST \
    https://api.basement.dev/v2/graphql \
    -H 'Content-Type: application/graphql' \
    -H 'X-Basement-API-Key: {key}' \
    -d '
    {
        transactions(limit: 3) {
            transactions {
                hash
            }
        }
    }
    '

Rate Limits​

The GraphQL API is rate-limited using a calculated query cost, capped per request. The total cost is determined by an estimated compute cost for Basement to fetch and calculated certain fields.

If a Query reaches the threshold of maximum complexity points, the query will not execute and you should try to split up your request in multiple requests.

Status Codes​

200 OK​

GraphQL’s status codes different than REST status codes. A request can produce errors or not execute and still return a 200 status code. As shown in the example below, you should always check the errors array.

{
  "data": {
    "token": {
      "name": "Capsule 10"
    }
  }
}

Error codes​

  • 402 Payment Required
    You provided an API key however its subscription is no longer active or has outstanding payments. Head over to billing.basement.dev to update your plan.
  • 429 Too Many Requests
    You submitted too many requests within a timeframe. Wait a while before sending a new request.
  • 5xx
    Something broke on our end – it’s probably best to retry. If the problem persists, reach out to our support at help.basement.dev

Pagination​

All root-level queries returning a list have support for pagination. Basement makes use of cursor based pagination, to prevent shifts in pages as soon as new blocks have been validated. Cursors are arbitrary data and should not be edited.

The response of a list root query represents a single page of objects. Within a page we can find the following data:

  • A field returning this page’s list of objects. This field is named after the type of object returned. Example: transactions , transactionLogs
  • The cursors field, returning an object containing a before and after field, which can be used in parameters
  • The totalCount field to find the amount of underlying objects in this list with the given filters.
tip

The totalCount field is capped at 10.000 for performance reasons. If a list is larger this field will have the value 10.000.

Parameters​

  • limit, optional, default is 50
    A limit on the number of objects to be returned in one page, between 1 and 50.
  • reversed, optional, default is false
    A boolean indicating whether the underlying list should be queried in reverse order before paginating.
  • after optional
    A cursor for use in pagination.
  • before optional
    A cursor for use in pagination.
{
  transactionLogs(
    filter: {
      addresses: ["0x7183209867489e1047f3a7c23ea1aed9c4e236e8"]
      topics: [["ArtChanged(uint256,uint256)"]]
    }
    limit: 5
    after: "g2wAAAACYgDy6lZhkmo="
  ) {
    transactionLogs {
      topics
      data
    }
    cursors {
      before
      after
    }
    totalCount
  }
}