API

Getting Started with the Rare Protocol GraphQL API

This guide will walk you through the steps to make your first query using Apollo Client in TypeScript. We'll perform the demo by querying for pool data based on a target address.

You can skip right to querying and exploring the whole api by visiting: https://api.rare.xyz/v1/graphql

What it is for?

The Rare Protocol Api provides access to a more broad set of data than the subgraph. It is designed for developers who wish to display complex data and metadata related to staking. It is good for both the current state of the staking protocol, as well as historical data, timeseries, analytics, and various metadata. It is also useful if you want to access known profiles for users, as well as token and marketplace data associated with staking users.

Prerequisites

Before you begin, make sure you have the following:

• Node.js and TypeScript installed on your machine.

• Basic knowledge of TypeScript

Step 1: Install Dependencies

First, install the necessary npm packages. Open your terminal and run the following command in your project directory:

$ npm install @apollo/client graphql

This will install Apollo Client and the GraphQL library, which are recommended to connect and interact with the GraphQL server.

Step 2: Set Up Apollo Client

Create a new TypeScript module named client.ts. This module will set up the Apollo Client. Insert the following code into a new file titled client.ts:

import {
  ApolloClient,
  InMemoryCache,
  gql,
  ApolloQueryResult,
} from '@apollo/client'

const client = new ApolloClient({
  uri: 'https://api.rare.xyz/v1/graphql',
  cache: new InMemoryCache(),
})

This code initializes an instance of Apollo Client, pointing to the GraphQL API endpoint and setting up a cache with InMemoryCache.

Step 3: Define the Query and Types

Next, define the GraphQL query and the corresponding TypeScript types for the response. This helps with type-safety and autocompletion in TypeScript. Add the following to your client.ts:

type GqlPoolResponse = {
  createdAt: string
  poolAddress: string
  accumulatorAddress: string
  target: {
    address: string
  }
  creator: {
    address: string
  }
}

Step 4: Execute the Query

Now, execute a query using the Apollo Client. We will query for pool data based on a specific target address. Append this code to your client.ts:

client
  .query({
    query: gql`
      query PoolsByTargetAddresses($targetAddresses: [String!]!) {
        poolsByTargetAddresses(targetAddresses: $targetAddresses) {
          createdAt
          poolAddress
          accumulatorAddress
          target {
            address
          }
          creator {
            address
          }
        }
      }
    `,
    variables: {
      targetAddresses: ['0x510FF10EFfd8b645D177b04541544DD54067C839'],
    },
  })
  .then((result: ApolloQueryResult<GqlPoolResponse>) =>
    console.log(JSON.stringify(result))
  )

This code sends a query to the GraphQL server and logs the response. The query method takes an object with two properties: query and variables. The query is defined using the gql template literal tag, and the variables object provides the specific target addresses.

Step 5: Run Your Code

To run your code, simply execute the client.ts script using Node.js or any TypeScript execution environment. You should see the query result output to your console.

$ npx ts-node ./src/client.ts

With this you've successfully set up your environment and executed a query to our GraphQL API using Apollo Client in TypeScript. This basic setup can be expanded to include more complex queries as needed for your application.

Other useful queries

Fetching a paginated list of pool details.

query AllPoolDetails($pagination: PaginationInput!) {
  allPoolDetails(pagination: $pagination) {
    pool {
      poolAddress
      target {
        address
        profile {
          sr {
            srName
          }
        }
      }
    }
    stakers {
      staker {
        profile {
          sr {
            srName
          }
        }
        address
      }
    }
    stats {
      stakerCount
      totalRewards
      totalStaked
      unswappedEth
    }
  }
}

variables = {
  pagination: {
    limit: 3,
    offset: 0,
    order: 'DESC',
    sortBy: 'stakerCount',
 }
}

Query a list of all the pools a user (or list of users) is staked in

query StakesByStakerAddresses($stakerAddresses: [String!]!) {
  stakesByStakerAddresses(stakerAddresses: $stakerAddresses) {
    pool {
      poolAddress
    }
    totalStaked
  }
}

variables = {
    stakerAddresses: ['0x510FF10EFfd8b645D177b04541544DD54067C839'],
}

Curl

You can also make or test graphql queries via curl requests. Here is an example of how to do that, with a trending pools query:

curl --request POST \
    --header 'content-type: application/json' \
    --url 'https://api.rare.xyz/v1/graphql' \
    --data '{"query":"query TrendingPools($pagination: PaginationInput!) {\n  trendingPools(pagination: $pagination) {\n    pool {\n      poolAddress\n    }\n    trendingRank\n    rankChange\n  }\n}","variables":{"pagination":{"limit":10,"offset":0,"order":"DESC"}}}'

This will return results from the api right in your terminal

Explore more:

The protocol api comes with a visual playground that you can use to explore the entire schema of available data and metadata. And test any query before using it in your application. You can access it at the following URL: https://api.rare.xyz/v1/graphql

Troubleshooting

Network Errors

Verify the API endpoint URL is correct, and that you included /v1/graphql on the end. Ensure your application has the necessary permissions to make outbound (egress) requests. If using a proxy or VPN, confirm it's not interfering with the requests.

Query Errors

Ensure your queries are syntactically correct. Use the visual playground to validate your queries against the schema before implementing them in your application. Pay special attention to field names, query structure, and required variables.

Handle Rate Limiting

Implement retry logic with exponential backoff in your application. Consider optimizing your query patterns to reduce the number of requests, such as using more specific queries to fetch only the data you need.

Correctly Use Pagination

A request that requires pagination will always require both a limit and offset variable. A sortBy and order field are only sometimes required when they make sense. The order field will always be either "ASC" or "DESC" and the sortBy fields will be named fields on the data you are querying, if applicable.

Use the Visual Playground

Leverage the visual playground not only for query validation but also to familiarize yourself with the schema, explore available queries and mutations, and understand the structure of responses. It's a powerful tool for learning and debugging.

Caching and Data Delays

The API relies on caching that might cause data to be delayed. If you're seeing unexpected delays. You can reach out with feedback on data freshness to the Rare Protocol team. There is also a txStatus query that can be used to check the status of a new transaction, which can be useful for checking the status of a transaction that might be causing a delay.