1 of 100

1.5.x

Documentation

Introduction

CSPR.cloud is an enterprise-grade middleware platform aimed to super-charge developers and to be the primary way for dApps to interact with the Casper Network. It provides access to indexed and enriched blockchain data, real-time streaming subscriptions, and access to reliable and maintained Casper Node. The APIs include:

Indexed and normalized network data
Integrations with the existing fungible and non-fungible (NFT) token standards, such as CEP-18, CEP-47, and CEP-78
Support of the existing smart contract-level event standards, such as , which is also natively supported by the
Relevant off-chain data, such as CSPR rates or
and more

CSPR.cloud was built with developer experience in mind and expands the Casper Node RPC API with more data points and querying possibilities, which are not available via the native node API. You can check for examples in the section.

Reference

To get familiar with CSPR.cloud, we recommend that you read these documents:

Learn about the general technical aspects of CSPR.cloud API, and how it works
Learn how to make your first API request and start your integration with the Casper Network
Learn about CSPR.cloud API possibilities, which aren't present in the Casper Node RPC API

Support

If you have any questions or run into any issues while using the CSPR.cloud Web API, you can find help in the . Here you can connect and get help from other developers.

Legal

By using CSPR.cloud, you agree to our and acknowledge that you have read our .

Overview

CSPR.cloud REST API is an HTTP-based API that dApps can use to programmatically query Casper network data. It has predictable resource-oriented endpoints and uses standard HTTP response codes, authentication, and verbs.

CSPR.cloud Streaming API is WebSocket-based and follows the WebSocket standard conventions.

Base URLs

The APIs can be accessed using the following base URLs

Mainnet

API

Base URL

Testnet

API

Base URL

Authorization

The API is protected and requires access tokens to be provided with each request. The access tokens identify the API user and their corresponding access tier limits. Visit the page to learn more.

Rate limits and quotas

The API is rate-limited, with rate limits defined by the user access tier. The total number of requests to each of the APIs is limited by monthly and daily quotas. Visit the page to learn more.

Responses

The API sends data in the JSON format. Successful REST API responses contain the data property, which contains the response data:

The Streaming API messages additionally include the action and timestamp properties:

Pagination

Requests that potentially may return an unlimited number of items are paginated. Endpoints that return paginated responses accept the page and limit query parameters to control the page and the number of items per page, correspondingly. Paginated responses contain two additional properties providing information on the total number of items and the total number of pages:

Visit the page to learn more.

Sorting

Some of the endpoints that return paginated responses provide a possibility to sort the results. Sorting is controlled by the order_by and order_direction query params. Visit the page to learn more.

Filtering

Some of the endpoints that return paginated responses provide a possibility to filter the results by certain properties. Available filter properties vary for different endpoints and are specified in the corresponding endpoint documentation. Visit the page to learn more.

Optional properties

Some of the endpoints provide a possibility to include optional properties into the responses using the includes query param. Visit the page to learn more.

Errors

Error responses contain the error property with optional code, message, and description properties providing more information about the error that occurred:

Visit the page to learn more.

Versions

This documentation covers CSPR.cloud V2. Click for CSPR.cloud V1 documentation, which will be deprecated soon.

Authorization

The CSPR.cloud API is exclusively available to registered users. To authorize your API requests, an access token is required. The access tokens identify the API user and their corresponding access tier limitations. Please visit the CSPR.cloud website to learn about the tiers and to submit an access token request. To learn more about rate limites and quotas please read the Rate limits and quotas documentation page.

Authorization header

The access token should be included in the Authorization header:

curl --request GET \
    'https://node.testnet.cspr.cloud/status' \
    --header "Authorization: 55f79117-fc4d-4d60-9956-65423f39a06a"

The access token provided in the example above is for the demonstration purposes only, and has limited capabilities.

To learn how to include the Authorization header in Casper SDKs to access the CSPR.cloud Casper Node please read the page.

Accessing from a browser

At this moment CPSR.cloud provides only the server side integration. By using your access token in a front-end application, you'll expose it to the world.

Reporting

You can request the usage report by sending an email from your registered account to .

Rate limits and quotas

At CSPR.cloud, we distinguish between rate limits and quotas to ensure efficient API management.

Rate limit

We impose a limit on the number of requests per minute. This measure helps manage load and avoid overloading our systems.

Quotas

Quotas control the overall call rates over an extended period, often tied to subscription tiers.

Long-term Management: Quotas determine the total number of calls that can be made in a set period, like a month.
Tier-based Access: For example, a free tier might allow 10,000 calls per month, while a premium tier could permit up to 10,000,000 calls in the same timeframe.

Exceeding these limits triggers a 429 error, signaling a rate limit breach.

Free tier limits

The free tier limits are set to ensure that you can test the API and integrate it into your application.

Mainnet

Service

Monthly quota

Daily quota

Rate limit /min

Testnet

Service

Monthly quota

Daily quota

Rate limit /min

Handling limits

To effectively manage your API usage and comply with rate limit or quota, consider the following strategies:

Upgrade to Premium Tier: If your needs exceed the free tier quota, consider upgrading to our Premium tier for higher limits. You can apply at .
Implement a Backoff-Retry Strategy: In cases where you encounter a 429 error (rate limit or quota exceeded), it's advisable to implement a backoff-retry strategy. This involves reducing the frequency of your API requests to stay within the allowed limits.
Monitor API Calls: Utilize logging tools to monitor your application’s API usage. This can help you identify patterns and optimize your request strategy to ensure efficient usage.

Adhering to these strategies will help you efficiently manage your API usage within the CSPR.cloud environment.

Pagination

REST API endpoints that potentially may return an unlimited number of items are paginated.

Requests

In addition to the endpoint-specific parameters, endpoints that return paginated responses accept the following pagination parameters to control the page and number of items per page correspondingly:

Parameter

Type

Default

Description

The maximum number of items per page is 250.

Responses

Paginated responses contain two additional properties providing information on the total number of items and the total number of pages:

Parameter

Type

Description

Example

Get the second page of accounts with 25 items per page:

Traversing results

When making an API request to an endpoint that returns paginated data, you usually don't receive all of the results in a single response. To traverse the data, you need to increment the page number in your requests until you collect all the required items. When doing so, note the . Setting the number of items per page to its maximum value of 250 will minimize the chances of being rate-limited for most of the use cases.

Note that if new objects are added to the list of items being paginated, the contents of each page will change.

Filtering

REST and WebSocket API endpoints that return multiple results may provide possibility to filter the data by certain properties. Not all properties can be used as filters. Please check the endpoint documentation to find out what properties are available for filtering.

Requests

To filter the results by a property, the corresponding property should be provided as a query param. Multiply filters can be used in one request to narrow down the data to what fits your dApp use-case. Some filters can accept multiple values separated by a comma.

Getting started

This tutorial will help you make your first API call to receive a list of NFT tokens in the CSPR.studio contract.

Prerequisites

We will use cURL to make API calls. You can install it from the curl.se website or by using the package manager of your choice.

Create an access token

Please register on to create a CSPR.cloud access token.

First API call

To fetch the NFT tokens in the contract we'll be using the . The endpoint requires a contract package hash, which we can find on :

Replace "[Your-Access-Token]" with your actual access token in each example.

What's next

Please proceed with the following documents to get familiar with CSPR.cloud:

Learn about the general technical aspects of CSPR.cloud API, and how it works
Learn about CSPR.cloud API possibilities, which aren't present in the Casper Node RPC API
Get familiar with the REST API reference to know what endpoints are available

Highlights

CSPR.cloud indexes and normalizes on-chain data to improve developers' experience when building on the Casper Network. Below are examples that demonstrate some of the possibilities CSPR.cloud offers. For the full list, please see the API reference pages.

Including related entities Receive related entities in a single response to minimize the number of network requests needed to load the data
Including CSPR rates Include CSPR rates that were relevant at the moment of a transfer, contract call, or reward creation
Include account info information provided by the account owner in the responses that contain account identifiers
Query granular pieces of the auction data that interest you, like all account delegations or a list of the current era validators
Query fungible token data relevant to your dApp
Query NFT movements and ownership from CSPR.cloud while focusing on the core business value of your application
Check aggregated historical contract costs to provide your users with better pricing
Translate account hashes to the corresponding public key for accounts that were observed on the network
Translate account main purses to the account public keys to better trace the fund movements
Subscribe to contract-level events the contracts from your dApps emit to track and aggregate the off-chain state for a better user experience

Including CSPR rates

Often, when looking at the fiat value of a native token amount, we want it to be converted using the rate that was relevant at the moment when the corresponding action happened. CSPR.cloud REST API provides the possibility to do so when requesting data having the timestamp property and when it's semantically acceptable To learn more, visit the page.

In the example below, we include the USD to CSPR rate in the account delegation rewards response by calling the rate with the USD currency ID as the argument in the includes query param:

Including account info

Accounts on Casper Mainnet and Testnet networks have the possibility to self-identify themselves in a decentralized with the Casper Account Info Standard smart contract. Many validators and contract owner accounts provide information about themselves to increase trust on the network.

CSPR.cloud REST API allows including account information to simplify the integration with the standard for dApps developers. Typically, account info standard data can be included in responses that contain account identifiers like account hashes or public keys.

In the example below, we'll include validator account info data in the account delegations API response. To demonstrate the possibility of filtering included object data, we'll request only the owner name and logo properties of the account info object.

curl -X 'GET' -G \
  'https://api.testnet.cspr.cloud/accounts/018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9/delegations' \
  --data-urlencode 'includes=validator_account_info{info{owner{name,branding{logo}}}}' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "bonding_purse": "uref-845ca8130882c27ee0da81252ed0deb7787796a3868df4b771e0518383d89a4b-007",
      "public_key": "018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9",
      "stake": "235732110487",
      "validator_account_info": null,
      "validator_public_key": "0196948158bf5b35c0c84f680f110b8debaa4e7628e13ba336a95651a214d3b9bd"
    },
    {
      "bonding_purse": "uref-a5bac0a17edeed284a0264f3fbbd189d3c4819f0e788a576792dc028c8476fba-007",
      "public_key": "018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9",
      "stake": "565388190696",
      "validator_account_info": {
        "info": {
          "owner": {
            "branding": {
              "logo": {
                "png_1024": "",
                "png_256": "https://picsum.photos/256/256",
                "svg": ""
              }
            },
            "name": "ACME"
          }
        }
      },
      "validator_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca"
    }
  ],
  "item_count": 2,
  "page_count": 1
}

Accessing auction data

CPSR.cloud provides granular access to the auction data, which is more convenient than parsing the results of the state_get_auction_info Casper RPC API method, through the following APIs:

Get bidder
Get bidders
Get validator

For example, fetching account delegations can be done with the following API request:

Accessing token data

Fungible tokens are one of the most used abstractions implemented on blockchains. CSPR.cloud allows dApp developers to focus on the core logic of their applications by tracking the token activity on the Casper Network for CEP-18 compatible tokens and providing APIs to query that data. CSPR.cloud provides a possibility to:

Get list of tokens owned by an account with their balances
Get list of token owners for a fungible token contract

Below is an example, that demonstrated fetching list of tokens owned by an account. Note, that we are about the contract package using the includes query parameter.

De-anonymizing account purses

Similarly to , CSPR.cloud can also "de-anonymize" account purses which can be used as the only transfer source or destination parameter. Let's have a look at transfers that happened in this for example.

The to_account_hash was not specified in the transfer parameters. Let's "de-anonymize" it by including the to_purse_public_key :

Note the to_purse_public_key property that was added in the second response. It contains the public key that corresponds to the account having the to_purse as its main purse. Please check to learn about all the optional data that can be included in the responses.

Resolving CSPR.name

CSPR.cloud REST API provides the possibility to resolve CSPR.name names either directly by calling the CSPR.name Resolution API or by including CSPR.name names as optional properties.

At the moment of writing this page (August 27th, 2024), the CSPR.name is not launched yet. That's why we added a test CSPR.name for the Faucet account to allow developers to implement and test their CSPR.name integration before the launch.

Direct CSPR.name to account hash resolution can be done using the Get CSPR.name resolution API and is recommended for the situations when you receive the name outside CSPR.cloud and want to resolve it to the corresponding account hash:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/cspr-name-resolutions/faucet.cspr' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": {
    "name_token_id": "0000000000000000000000000000000000000000000000000000000000000000",
    "name": "faucet.cspr",
    "resolved_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
    "expires_at": "2124-08-27T12:00:00Z"
  }
}

In situations, when you want to resolve account hashes to the corresponding CSPR.name names, in most of the cases it's possible to do by requesting CSPR.name as optional property in the includes query parameter:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/deploys/872394dcb8ac58b61f543e6fa0e3425b1db6b83a03d9d46cbf55c9d4b736624f?includes=caller_cspr_name' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

If you want to find the primary CSPR.name for an account, you can include it in the Get account API:

REST API

Reference

This is a full list of the available CSPR.cloud REST API entities. Some of the entities are presented as root-level resources, and some represent related information of the root-level resources and are presented as their edges. The endpoints associated with each entity provide all the relevant data about that entity. Value objects that provide a mapping between identifiers and names aren't listed here and are documented with the corresponding endpoint documentation.

Entities may have relations to other entities. Such relations are exposed by the presence of one entity identifier in the other entity properties. Typically, it means that this identifier can be used as a in the API requests and that the related entity could be included in the responses as an .

Entity

Description

Get account

Get account by its identifier (public key or account hash)

Query params

None

Sorting

None

Optional properties

Property

Type

Description

Response

Example

Auction metrics

The AuctionMetrics entity represents calculated metrics for the era retrieved from auction info

Properties

The AuctionMetrics entity has the following properties:

Property

Type

Optional properties

None

Response

List of value objects describing the available contract types

Example

Contract entry point

The ContractEntryPoint entity offers a normalized representation of the Casper Network EntryPoint. Entry points are associated with the Contract entity and describe how to interact with it. In CSPR.Cloud, only the name of the entry point and its relations to the Contract and ContractPackage are stored.

Properties

The ContractEntryPoint entity has the following properties:

Property

Type

Description

Example

Optional properties

None

Relations

The ContractEntryPoint entity has the following relations with other entities:

Entity

Mapping property

Description

Endpoints

The ContractEntryPoint entity has the following endpoints:

Relation endpoints

Get contract entry points

Get contract entry points by contract hash

GET /contracts/{contract_hash}/entry-points

Query params

None

Sorting

None

Optional properties

None

Response

Example

Get contract package

Get a contract package by its identifier (contract package hash).

This endpoint allows you to retrieve detailed information about a specific contract package using its unique identifier, the contract package hash. The response includes various properties such as owner public key, name, description, metadata, latest version contract type ID, timestamp, icon URL, and deploys number.

Query params

None

Sorting

None

Optional properties

Property

Type

Description

Response

Example

Delegation

The Delegation entity represents a record of a delegation transaction in the context of Casper Network

Properties

The Delegation entity has the following properties:

Property

Get account delegations

Get paginated list of delegations made by an account.

Query params

None

Get total validator delegators' rewards

Get total amount of delegator rewards for a validator.

GET /validators/{public_key}/total-delegator-rewards

Query params

None

Sorting

None

Optional properties

None

Response

uint64

Example

Get deploy execution types

Get deploy execution types.

Query params

Response

Example

Get NFT standards

Query params

None

Sorting

Get off-chain NFT metadata statuses

Query params

None

Get CSPR.name resolution

Get CSPR.name resolution by name

Query params

None

Sorting

Get historical currency rates

Get a paginated list of historical currency rates for the given time range.

Query params

Query param

Description

from

Start of the range in the format

Sorting

Property

Description

Default sorting is created ASC

Optional properties

None