Overview

8Pay's offers RESTful APIs quick answers without the need to directly interact with the blockchain. The APIs, which are controlled and hosted by 8pay, read from a cached version of the information stored on the blockchain. Everybody can verify all of the information provided by the 8pay APIs with onchain data to ensure that it is accurate and up to date.

Authentication

The way to authenticate on 8Pay API is through an api key that can be created in the API Keys section of the 8Pay's web app.

This api key can then be used in the Headers section of your HTTP request:

Authorization: Bearer [API KEY]

Pagination

API endpoints returning lists of objects can have a lot of items and are thus paginated.

Pagination can be controlled passing the following query parameters in your HTTP request:

  • limit: the number of items to fetch in the request (default 100, max 1000)

  • offset: an arbitrary offset at which to start retrieving items (default 0)

The formatting of a paginated result is always:

{
"data": [],
"limit": 100,
"offset": 0,
"total": 10
}

For simplicity, only the data field will be shown from now on.

Errors

8Pay uses conventional HTTP response codes to indicate the success or failure of an API request.

As a general rule:

  • Codes in the 2xx range indicate success

  • Codes in the 4xx range indicate incorrect or incomplete parameters (e.g., a required parameter was omitted, an operation failed with a 3rd party, etc.)

  • Codes in the 5xx range indicate an error with 8Pay's servers (these are rare)

8Pay also outputs an error message and an error code formatted in JSON:

{
"error": {
"code": 404,
"message": "Page not found"
}
}

Transactions

Every operation on the blockchain is performed sending a transaction, uniquely identified by an hash. This identifier will be referred to as transactionHash in API responses.

Due to blockchain nature, the results produced by a transaction included in a block are not immediately final and can be reverted if a reorganization occurs. Finality is probabilistic and increases with the number of subsequent blocks mined after the block containing the transaction.

8Pay waits for 15 confirmation blocks before considering transactions final and classifies them as:

  • unconfirmed: when the transaction can still be subject to reorganizzations

  • confirmed: when the transaction is considered final

  • failed: when the transaction has been reverted

This status is referred to as transactionStatus.

At this time, the public APIs only support confirmed transactions.