1 of 8

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

CSPR.cloud REST API

CSPR.cloud Streaming API

Casper Node RPC API

Casper Node SSE API

Testnet

API

Base URL

CSPR.cloud REST API

CSPR.cloud Streaming API

Casper Node RPC API

Casper Node SSE API

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 Authorization 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 Rate limits and quotas 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:

{
    "data": <ResponseData>
}

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

{
    "action": <string>,
    "data": <MessageData>,
    "timestamp": <datetime>
}

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:

{
    "data": [<ResponseData>],
    "item_count": <int>,
    "page_count": <int>
}

Visit the Pagination 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 Sorting 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 Filtering 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 Optional properties 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:

{
    "error": {
        "code": 404,
        "message": "The requested block was not found"
    }
}

Visit the Errors page to learn more.

Versions

This documentation covers CSPR.cloud V2. Click here 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 Connecting with an SDK 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 support@cspr.cloud.

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

Handling limits

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

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.
Lazy Loading Technique: To reduce unnecessary API calls, implement lazy loading in your application. Trigger API calls based on user interactions, such as clicking a button or reaching a specific section of a page, to minimize the number of requests.

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

page

int

1

Page number

page_size

int

10

Number of items per page

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

item_count

int

Total number of items

page_count

int

Total number of pages

Example

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

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts?page=2&page_size=25' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "account_hash": "37f304a6632b214eacc45b85f6a45759194ea69f6684da0bca42d60e42ac8e12",
      "balance": 3050076259180,
      "main_purse_uref": "uref-692b5b8afcad47b0dee74962540a01ea1402fc0c9c84d9474e5766775373795c-007",
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c"
    },
    {
      "account_hash": "7894d8458c82388f6d276c07c1c52033ac37b175fa722b9cc40e7a0157ce17fc",
      "balance": 252442325961483,
      "main_purse_uref": "uref-c4afe0fb020ebcdc940289d759499ff5fb87e999567e4d61d836d70bfad20a55-007",
      "public_key": "0145fb72c75e1b459839555d70356a5e6172e706efa204d86c86050e2f7878960f"
    },
    ...
    {
      "account_hash": "eb108759cf29b5d1ce6a311989890170d94bb98e06e4097e4ee20c18d6bf4f16",
      "balance": 80331298738010,
      "main_purse_uref": "uref-fd73e477cbbeb134ebb7fee8ccb423c8d45c88e23bd82d2d1104fc7f34f3a27b-007",
      "public_key": "0154d4c09bcae885fdd3dc0bf8ac7fa23ae281baf60a5b352b1ff0b505a65e1285"
    }
  ],
  "item_count": 63584,
  "page_count": 2544
}

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 rate limits. 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.

Sorting

REST API endpoints that return paginated responses may provide a possibility to sort the results by one of the result properties. Not all properties can be used for sorting. Please check the endpoint documentation to find out the sorting properties.

Requests

In addition to the endpoint-specific parameters, endpoints that return sorted results accept the following parameters to control the sorting property and the order:

Parameter

Type

Description

order_by

string

Sorting property the results should be sorted by

order_direction

string

Order direction: ASC or DESC

The defaults are different for different endpoints and are provided in the corresponding endpoint documentation.

Example

Get blocks sorted by height from lowest to highest:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/blocks?order_by=block_height&order_direction=ASC' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "block_height": 0,
      "block_hash": "975ea4de188c2a67946188cea0ec8a93d2d38286d7642526d50c45839a291210",
      "parent_block_hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "state_root_hash": "e88b7c061760134ba37ad312c1e2d6373121748e9c61bcea19cc57510829addf",
      "era_id": 0,
      "proposer_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca",
      "native_transfers_number": 0,
      "contract_calls_number": 0,
      "is_switch_block": false,
      "timestamp": "2021-04-08T17:00:57Z"
    },
    {
      "block_height": 1,
      "block_hash": "f8ebb3a81c9c70faeaec896c94e7e56c75a5e1548e1b8dfe639c1b31610e5d22",
      "parent_block_hash": "975ea4de188c2a67946188cea0ec8a93d2d38286d7642526d50c45839a291210",
      "state_root_hash": "e88b7c061760134ba37ad312c1e2d6373121748e9c61bcea19cc57510829addf",
      "era_id": 0,
      "proposer_public_key": "017d96b9a63abcb61c870a4f55187a0a7ac24096bdb5fc585c12a686a4d892009e",
      "native_transfers_number": 0,
      "contract_calls_number": 0,
      "is_switch_block": false,
      "timestamp": "2021-04-08T17:02:02Z"
    },
    ...
    {
      "block_height": 9,
      "block_hash": "590f7b20a276ef7a2a2fba6871ad781a56fad16daa0ee80b4f214f7870652255",
      "parent_block_hash": "2e601c65dbfde43948eef998b8ab5c68d9f95b35612eb0245444903ea419c185",
      "state_root_hash": "f6985aa0d6dc760fd651f5d86bb3ecb7b9d3b56860b437aa83a0fa489dab9d3b",
      "era_id": 0,
      "proposer_public_key": "017d96b9a63abcb61c870a4f55187a0a7ac24096bdb5fc585c12a686a4d892009e",
      "native_transfers_number": 0,
      "contract_calls_number": 3,
      "is_switch_block": false,
      "timestamp": "2021-04-08T17:10:47Z"
    }
  ],
  "item_count": 2291305,
  "page_count": 229131
}

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.

Example

Filter NFT tokens by owner and contract package:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/nft-tokens?owner_hash=8c9675894eb753007c17058b4616dee224171365f0ac5e161152b1e5c95ce944&contract_package_hash=998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "contract_package_hash": "998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821",
      "is_burned": false,
      "offchain_metadata": null,
      "offchain_metadata_status": 0,
      "onchain_metadata": "eyJuYW1lIjogIlF1aWV0IHBsYWNlcyIsICJhc3NldCI6ICJodHRwczovL21hcml0aW1lLnNlYWxzdG9yYWdlLmlvL21ha2UvOTk4YWY2ODI1ZDc3ZGExNS9iMzQ0NzhkMzkyNjY0OGEyODkzZWNlM2NiNzJiMGIwMSIsICJkZXNjcmlwdGlvbiI6ICJhIGxvZnQgIn0=",
      "owner_hash": "8c9675894eb753007c17058b4616dee224171365f0ac5e161152b1e5c95ce944",
      "owner_type": 0,
      "timestamp": "2022-12-06T18:41:41Z",
      "token_id": "13",
      "token_standard_id": 1,
      "tracking_id": 21455
    },
    {
      "contract_package_hash": "998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821",
      "is_burned": false,
      "offchain_metadata": null,
      "offchain_metadata_status": 0,
      "onchain_metadata": "eyJuYW1lIjogImxpYnJhcnkiLCAiYXNzZXQiOiAiaHR0cHM6Ly9tYXJpdGltZS5zZWFsc3RvcmFnZS5pby9tYWtlLzk5OGFmNjgyNWQ3N2RhMTUvNTQ0ZjI5ZDJiOTZmNDc1ZjhmYWMwMmJmMzY5ZWM2MGUiLCAiZGVzY3JpcHRpb24iOiAiYW5vdGhlciBjb29sIHF1aWV0IHBsYWNlIn0=",
      "owner_hash": "8c9675894eb753007c17058b4616dee224171365f0ac5e161152b1e5c95ce944",
      "owner_type": 0,
      "timestamp": "2022-12-06T18:44:45Z",
      "token_id": "14",
      "token_standard_id": 1,
      "tracking_id": 21456
    }
  ],
  "item_count": 2,
  "page_count": 1
}

Optional properties

Most of the REST API endpoints allow optional data to be included in their responses. It could be related entities, derived properties, account info standard data, or CSPR rates at the moment of the entity creation. Please check the endpoint documentation to find out what optional properties could be included in the responses.

Requests

Optional data can be included using the includes query param that specifies a comma-separated list of all optional data that should be included. The includes query param options can be one of three forms:

Scalar values

To include a scalar value its name should be specified the includes list.

Objects

Similar to scalar values to include an object its name should be specified in the includes list. However, for objects it's possible to specify a subset of fields that should be returned using the object querying syntax, which looks like this:

includes=account_info{info{owner{name,branding{logo}}}}

The request above will return only the name and the branding.logo properties of the account info object

Functions

When the included data requires extra parameters, it is included as a function. The function form provides a possibility to specify the needed input. For example, to include the USD to CSPR rate, the USD currency ID 1 should be passed as a parameter to the rate function, like this:

includes=rate(1)

Examples

Scalar values

The WriteTransfer transforms that are used to track the native token transfers, contain the recipient account hash. It's possible, however, to include the corresponding public key if it is known to us. To learn more, visit the Transfer REST API page.

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

{
  "data": [
    {
      "amount": "2500000000",
      "deploy_hash": "0000015dd8b8065e31af7785cd174fa10bebf380f39515ffc3a8a536aee819a0",
      "from_purse": "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-007",
      "id": 0,
      "initiator_account_hash": "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456",
      "timestamp": "2021-10-12T06:20:59Z",
      "to_account_hash": "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6",
      "to_public_key": "01da93a224201b9936f535502643fe07a922b2010993cdad093acb0112d810c1a8",
      "to_purse": "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-004",
      "transform_key": "c3fca49f9193ec730e9170a02360d0a96d9f3c07c9b898b6c6494d67b417d886"
    },
    {
      "amount": "2500000000",
      "deploy_hash": "00000498bf7c3994f804a4f8a99378350e02ebf5633774ced4faa2ae6dad88a3",
      "from_purse": "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-007",
      "id": 0,
      "initiator_account_hash": "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6",
      "timestamp": "2021-10-13T12:26:47Z",
      "to_account_hash": "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456",
      "to_public_key": "01c978cd9eb96143ed89f0523c07787207ff4eb84756197a6a1d9093bcd51da4ed",
      "to_purse": "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-004",
      "transform_key": "7fd3d2892dc61f43269a55aaeec21158c283717549caf7a820e9cfa966e6df1d"
    },
    ...
    {
      "amount": "1000000000000",
      "deploy_hash": "000026eeab921c16335f65f54ea050efca9cf352840a1025f87b4deaa3bbdd95",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": null,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "timestamp": "2021-10-20T23:59:25Z",
      "to_account_hash": "1b43092d00330439d874c1e4b38bf68b6c9a043aacf72da350e65e46d13e0c51",
      "to_public_key": "01ec83a2a60742294ab33aa86b6cd6c71662d1f37e9a270edc1e768e1a7deaa5c7",
      "to_purse": "uref-f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480-004",
      "transform_key": "f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480"
    }
  ],
  "item_count": 5297116,
  "page_count": 529712
}

Objects

An entity is called related if its identifier is present among the requested entity's properties. To include a related entity you need to specify its name in the includes query param. In the example below, we include contract package and contract entry point objects in the deploy list data. To learn more, visit the Including related entities page.

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

{
  "item_count": 6664918,
  "page_count": 666492,
  "data": [
    {
      "args": {
        "amount": {
          "cl_type": "U512",
          "parsed": "100000000000"
        },
        "post_id": {
          "cl_type": "U64",
          "parsed": 1
        },
        "source_purse": {
          "cl_type": "URef",
          "parsed": "uref-dbee6bd5057140ef79760ff97ee225f219c095a6b520e9fdb1083005b3e91adf-007"
        }
      },
      "block_hash": "2f535ee1f7a841bf33fb3af6c841ee5ac81b331e4f033e2700829800d406cd6a",
      "caller_public_key": "019d71f9869046408292ec32e78e613ac5f7b320fd268cd8c0ae3c95dc5d6dca62",
      "contract_entrypoint": {
        "action_type_id": null,
        "contract_hash": "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0",
        "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
        "id": 1685659,
        "name": "bid"
      },
      "contract_hash": "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0",
      "contract_package": {
        "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
        "description": null,
        "icon_url": null,
        "latest_version_contract_type_id": null,
        "metadata": {},
        "name": null,
        "owner_public_key": "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1",
        "timestamp": "2023-12-17T16:32:42Z"
      },
      "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
      "cost": "20894638930",
      "deploy_hash": "c2a83a2409f65447d8495768a6f99fee7247135680461ed4b3d6d936995c7630",
      "entry_point_id": 1685659,
      "error_message": null,
      "execution_type_id": 2,
      "payment_amount": "150000000000",
      "status": "processed",
      "timestamp": "2023-12-17T17:52:39Z"
    },
    ...
    {
      "args": {
        "token_owner": {
          "cl_type": "Key",
          "parsed": {
            "Account": "account-hash-2142a81faac0670b76ef0e1be2925ddb9cd7493cc99b2fa591161b82c808a7e3"
          }
        }
      },
      "block_hash": "0daaee30d1a87b4323221e43d08ce4365ab88681f47b18cc247336fa6773d731",
      "caller_public_key": "014d657f276686b711251f32fb9fa36c0852aaab43f4f6bb6cbc7794d4d54cf67e",
      "contract_entrypoint": {
        "action_type_id": null,
        "contract_hash": "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0",
        "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
        "id": 1685652,
        "name": "register_owner"
      },
      "contract_hash": "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0",
      "contract_package": {
        "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
        "description": null,
        "icon_url": null,
        "latest_version_contract_type_id": 7,
        "metadata": {
          "burn_mode": 0,
          "events_mode": 0,
          "holder_mode": 2,
          "identifier_mode": 0,
          "metadata_mutability": 1,
          "minting_mode": 1,
          "name": "enhanced-nft-1",
          "nft_kind": 1,
          "nft_metadata_kind": 0,
          "ownership_mode": 2,
          "symbol": "ENFT-1",
          "total_supply_uref": "uref-bc550f42fe8898a51bc0daae90ce910f4b5a042a306efa8f95032813089ad195-007",
          "whitelist_mode": 0
        },
        "name": "enhanced-nft-1",
        "owner_public_key": "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1",
        "timestamp": "2023-12-17T16:29:40Z"
      },
      "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
      "cost": "681461970",
      "deploy_hash": "be2db151ba267cff9630b54c45b0aeb704d7d512f12670f7995af7cedad27d27",
      "entry_point_id": 1685652,
      "error_message": null,
      "execution_type_id": 2,
      "payment_amount": "5000000000",
      "status": "processed",
      "timestamp": "2023-12-17T17:26:36Z"
    }
  ]
}

Functions

Entities that have the timestamp property can optionally include the CSPR rate at that time in the requested currency, which is passed as an argument to the rate function. In the example below, we include the USD to CSPR rate in the account transfers response. To learn more, visit the Including CSPR rates page.

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts/8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f/transfers?includes=rate(1)' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "amount": "10000000000000",
      "deploy_hash": "4237b9518b7f0dda69235fedc92badd4e5206cd9b3ad2e9f599fe34416d9e3ab",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": 20230516,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "rate": 0.0488488,
      "timestamp": "2023-05-16T22:01:16Z",
      "to_account_hash": "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f",
      "to_purse": "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004",
      "transform_key": "abf1343e47952a57ab001ec423398a773dfd96f3f32a905daeb6bc47db0db2dc"
    },
    {
      "amount": "1000000000000",
      "deploy_hash": "4d14f8f9cd95aabdfdea930aa9472bf966264d25f57986b005810e11d1c05017",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": null,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "rate": 0.0295418,
      "timestamp": "2022-11-14T13:14:02Z",
      "to_account_hash": "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f",
      "to_purse": "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004",
      "transform_key": "b0a27297a03107cd66c270d9bc7b33086f3ceb9c2e8c4058e72a4285c73273bd"
    }
  ],
  "item_count": 2,
  "page_count": 1
}

The rate property of the first result in the response above holds the CSPR rate from May 16th, 2023, and the second result has the rate from November 11th, 2022.

Errors

Requests made to our APIs can result in several different error responses. The following document describes error values.

Properties

The Error has the following properties:

Property

Type

Description

code

string

Error code constant represented as a string

message

string

Error message depending on the type of error and an API resource

Error Types

Code

Name

HTTP Status Code

Description

invalid_input

InvalidParamError

400

Invalid client input parameters

unauthorized

UnauthorizedError

401

Client is not authorized

access_denied

AccessDeniedError

403

Entity or resource access is forbidden

not_found

NotFoundError

404

Entity not found

duplicate_entity

DuplicateEntityError

409

Entity already exist

Example

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

{
  "error": {
    "code": "invalid_input",
    "message": "AccountHash identifier is not a valid account hash or public key"
  }
}

Rate limiting errors

Visit the Rate limits and quotas for more information regarding Rate limiting errors.

Optional properties

Requests

Scalar values

To include a scalar value its name should be specified the includes list.

Objects

includes=account_info{info{owner{name,branding{logo}}}}

The request above will return only the name and the branding.logo properties of the account info object

Functions

includes=rate(1)

Examples

Scalar values

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

{
  "data": [
    {
      "amount": "2500000000",
      "deploy_hash": "0000015dd8b8065e31af7785cd174fa10bebf380f39515ffc3a8a536aee819a0",
      "from_purse": "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-007",
      "id": 0,
      "initiator_account_hash": "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456",
      "timestamp": "2021-10-12T06:20:59Z",
      "to_account_hash": "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6",
      "to_public_key": "01da93a224201b9936f535502643fe07a922b2010993cdad093acb0112d810c1a8",
      "to_purse": "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-004",
      "transform_key": "c3fca49f9193ec730e9170a02360d0a96d9f3c07c9b898b6c6494d67b417d886"
    },
    {
      "amount": "2500000000",
      "deploy_hash": "00000498bf7c3994f804a4f8a99378350e02ebf5633774ced4faa2ae6dad88a3",
      "from_purse": "uref-6626e023ab7ab4837be36a9e61dffcfe239d987039727c9f56408527e48d3968-007",
      "id": 0,
      "initiator_account_hash": "a8ae349a49ede9df992637e4c9141b5075352b4d607711bd1cf30a76403406c6",
      "timestamp": "2021-10-13T12:26:47Z",
      "to_account_hash": "42204997767147bb78f0045b50272cdfbf90bd10544f9e51d66e0560166de456",
      "to_public_key": "01c978cd9eb96143ed89f0523c07787207ff4eb84756197a6a1d9093bcd51da4ed",
      "to_purse": "uref-b8b87efb3d0f6d6f5f4b3bed8a9b017acfcb7ecaf555ec42d852864622e71c9b-004",
      "transform_key": "7fd3d2892dc61f43269a55aaeec21158c283717549caf7a820e9cfa966e6df1d"
    },
    ...
    {
      "amount": "1000000000000",
      "deploy_hash": "000026eeab921c16335f65f54ea050efca9cf352840a1025f87b4deaa3bbdd95",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": null,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "timestamp": "2021-10-20T23:59:25Z",
      "to_account_hash": "1b43092d00330439d874c1e4b38bf68b6c9a043aacf72da350e65e46d13e0c51",
      "to_public_key": "01ec83a2a60742294ab33aa86b6cd6c71662d1f37e9a270edc1e768e1a7deaa5c7",
      "to_purse": "uref-f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480-004",
      "transform_key": "f4d64726bf61c2b1f53ce9b137a64a063e8225a98f1cb6ed1a9966ccf983b480"
    }
  ],
  "item_count": 5297116,
  "page_count": 529712
}

Objects

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

{
  "item_count": 6664918,
  "page_count": 666492,
  "data": [
    {
      "args": {
        "amount": {
          "cl_type": "U512",
          "parsed": "100000000000"
        },
        "post_id": {
          "cl_type": "U64",
          "parsed": 1
        },
        "source_purse": {
          "cl_type": "URef",
          "parsed": "uref-dbee6bd5057140ef79760ff97ee225f219c095a6b520e9fdb1083005b3e91adf-007"
        }
      },
      "block_hash": "2f535ee1f7a841bf33fb3af6c841ee5ac81b331e4f033e2700829800d406cd6a",
      "caller_public_key": "019d71f9869046408292ec32e78e613ac5f7b320fd268cd8c0ae3c95dc5d6dca62",
      "contract_entrypoint": {
        "action_type_id": null,
        "contract_hash": "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0",
        "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
        "id": 1685659,
        "name": "bid"
      },
      "contract_hash": "8069372ccd59c538d93404313182f8c47579b5aa4fe23060ae2f6ef83a4aa7c0",
      "contract_package": {
        "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
        "description": null,
        "icon_url": null,
        "latest_version_contract_type_id": null,
        "metadata": {},
        "name": null,
        "owner_public_key": "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1",
        "timestamp": "2023-12-17T16:32:42Z"
      },
      "contract_package_hash": "b67106c2381b719a2e310e0598847d75ac37381471e318ae112a85e79b96e9ad",
      "cost": "20894638930",
      "deploy_hash": "c2a83a2409f65447d8495768a6f99fee7247135680461ed4b3d6d936995c7630",
      "entry_point_id": 1685659,
      "error_message": null,
      "execution_type_id": 2,
      "payment_amount": "150000000000",
      "status": "processed",
      "timestamp": "2023-12-17T17:52:39Z"
    },
    ...
    {
      "args": {
        "token_owner": {
          "cl_type": "Key",
          "parsed": {
            "Account": "account-hash-2142a81faac0670b76ef0e1be2925ddb9cd7493cc99b2fa591161b82c808a7e3"
          }
        }
      },
      "block_hash": "0daaee30d1a87b4323221e43d08ce4365ab88681f47b18cc247336fa6773d731",
      "caller_public_key": "014d657f276686b711251f32fb9fa36c0852aaab43f4f6bb6cbc7794d4d54cf67e",
      "contract_entrypoint": {
        "action_type_id": null,
        "contract_hash": "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0",
        "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
        "id": 1685652,
        "name": "register_owner"
      },
      "contract_hash": "f07497ba5e71e52643e620d4722419c22870638ee3f5412c9cbc204c00b3b0b0",
      "contract_package": {
        "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
        "description": null,
        "icon_url": null,
        "latest_version_contract_type_id": 7,
        "metadata": {
          "burn_mode": 0,
          "events_mode": 0,
          "holder_mode": 2,
          "identifier_mode": 0,
          "metadata_mutability": 1,
          "minting_mode": 1,
          "name": "enhanced-nft-1",
          "nft_kind": 1,
          "nft_metadata_kind": 0,
          "ownership_mode": 2,
          "symbol": "ENFT-1",
          "total_supply_uref": "uref-bc550f42fe8898a51bc0daae90ce910f4b5a042a306efa8f95032813089ad195-007",
          "whitelist_mode": 0
        },
        "name": "enhanced-nft-1",
        "owner_public_key": "01a0c97ba1ba5a973eeee369e9480ea15665278699873876a18eaf09c361f8e9c1",
        "timestamp": "2023-12-17T16:29:40Z"
      },
      "contract_package_hash": "7c7a462c55ed3f3631a933e46315a072adaa38105a4160df3a00823495f53e41",
      "cost": "681461970",
      "deploy_hash": "be2db151ba267cff9630b54c45b0aeb704d7d512f12670f7995af7cedad27d27",
      "entry_point_id": 1685652,
      "error_message": null,
      "execution_type_id": 2,
      "payment_amount": "5000000000",
      "status": "processed",
      "timestamp": "2023-12-17T17:26:36Z"
    }
  ]
}

Functions

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts/8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f/transfers?includes=rate(1)' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "amount": "10000000000000",
      "deploy_hash": "4237b9518b7f0dda69235fedc92badd4e5206cd9b3ad2e9f599fe34416d9e3ab",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": 20230516,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "rate": 0.0488488,
      "timestamp": "2023-05-16T22:01:16Z",
      "to_account_hash": "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f",
      "to_purse": "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004",
      "transform_key": "abf1343e47952a57ab001ec423398a773dfd96f3f32a905daeb6bc47db0db2dc"
    },
    {
      "amount": "1000000000000",
      "deploy_hash": "4d14f8f9cd95aabdfdea930aa9472bf966264d25f57986b005810e11d1c05017",
      "from_purse": "uref-b06a1ab0cfb52b5d4f9a08b68a5dbe78e999de0b0484c03e64f5c03897cf637b-007",
      "id": null,
      "initiator_account_hash": "b383c7cc23d18bc1b42406a1b2d29fc8dba86425197b6f553d7fd61375b5e446",
      "rate": 0.0295418,
      "timestamp": "2022-11-14T13:14:02Z",
      "to_account_hash": "8acedb18a06c3b1b0823334f5b6fea53b2f6bc50f792de401b1f561bc214ba1f",
      "to_purse": "uref-fb2c1f47c593e5f27735c92217d7c99f85516467a1cb446214ae22fc46d8559e-004",
      "transform_key": "b0a27297a03107cd66c270d9bc7b33086f3ceb9c2e8c4058e72a4285c73273bd"
    }
  ],
  "item_count": 2,
  "page_count": 1
}

The rate property of the first result in the response above holds the CSPR rate from May 16th, 2023, and the second result has the rate from November 11th, 2022.