REST API Reference

The REST API provides a simple HTTP interface for querying blockchain data on IOST Layer 2. This API is primarily used by block explorers and applications that need to retrieve on-chain data without implementing complex JSON-RPC calls.

Endpoint

The base REST API endpoint for IOST Layer 2 is: https://l2-scan.iost.io/api

Authentication

The REST API is publicly accessible without authentication for read-only operations. Rate limits may apply to prevent abuse.

API Categories

Block Data

Endpoint	Method	Description
/blocks	GET	Returns a list of recently mined blocks
/blocks/{blockNumber}	GET	Returns details for a specific block by number
/blocks/{blockHash}	GET	Returns details for a specific block by hash
/blocks/transactions/{blockNumber}	GET	Returns all transactions in a block

Transaction Data

Endpoint	Method	Description
/transactions	GET	Returns a list of recent transactions
/transactions/{txHash}	GET	Returns details for a specific transaction
/transactions/pending	GET	Returns list of pending transactions
/transactions/execution-status/{txHash}	GET	Returns execution status of a transaction

Account Data

Endpoint	Method	Description
/addresses/{address}	GET	Returns account details and balance
/addresses/{address}/transactions	GET	Returns transactions for an account
/addresses/{address}/token-balances	GET	Returns all token balances for an address
/addresses/{address}/logs	GET	Returns logs emitted by contract interactions at this address

Token Data

Endpoint	Method	Description
/tokens	GET	Returns a list of tokens on the network
/tokens/{contractAddress}	GET	Returns details for a specific token
/tokens/{contractAddress}/holders	GET	Returns top token holders
/tokens/{contractAddress}/transfers	GET	Returns recent token transfers

Contract Data

Endpoint	Method	Description
/contracts/{address}	GET	Returns details about a smart contract
/contracts/{address}/methods	GET	Returns contract method signatures
/contracts/{address}/events	GET	Returns events emitted by the contract
/contracts/verification	POST	Submit contract for verification

Statistics

Endpoint	Method	Description
/stats	GET	Returns network statistics (TPS, gas price, etc.)
/stats/charts/transactions	GET	Returns transaction count over time
/stats/charts/market	GET	Returns token price information
/stats/validators	GET	Returns information about validators

Common Query Parameters

Most GET endpoints support the following query parameters:

Parameter	Description	Example
page	Page number for paginated results	?page=2
limit	Number of results per page (max: 100)	?limit=50
sort	Field to sort by (with optional direction)	?sort=timestamp:desc
startDate	Filter by start date (UNIX timestamp)	?startDate=1633046400
endDate	Filter by end date (UNIX timestamp)	?endDate=1633132800

Response Format

All REST API responses are returned in JSON format with a consistent structure:

{
  "status": "success",
  "data": {
    // Response data here
  },
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1000,
    "pages": 40
  }
}

Error Handling

When an error occurs, the API returns appropriate HTTP status codes along with an error response:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found"
  }
}

Common HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Example Usage

Below is a sample code snippet in Python that demonstrates how to query recent blocks using the REST API:

import requests

def get_recent_blocks(page=1, limit=10):
    url = "https://l2-scan.iost.io/api/blocks"
    params = {"page": page, "limit": limit}
    response = requests.get(url, params=params)
    if response.status_code == 200:
        data = response.json()
        return data.get("data")
    else:
        print("Error:", response.status_code, response.text)
        return None

# Example: Get recent blocks
if __name__ == "__main__":
    blocks = get_recent_blocks()
    print("Recent Blocks:")
    print(blocks)

Pagination

Results from list endpoints are paginated by default. The pagination information is included in the response:

• Default page size: 25 items
• Maximum page size: 100 items
• Page numbering starts at 1

To navigate through pages, use the page and limit parameters:

GET /api/transactions?page=2&limit=50

Additional Notes

• All timestamps are returned in UNIX format (seconds since epoch).
• Addresses should be provided in standard Ethereum format (0x-prefixed hexadecimal).
• Block numbers can be provided as integers or hexadecimal strings.
• Transaction hashes should include the 0x prefix.

Resources

For more information, visit the BlockScout Documentation, which provides the underlying technology for the IOST Layer 2 explorer.