API Reference

Introduction

IOST Layer 2 provides a comprehensive suite of APIs that enable developers to interact with the blockchain, query data, and build decentralized applications. These APIs serve as the gateway between your applications and the IOST Layer 2 network, offering multiple interfaces tailored to different development needs.

What Are IOST Layer 2 APIs?

IOST Layer 2 APIs are programming interfaces that allow developers to:

• Query blockchain state and data
• Submit transactions to the network
• Deploy and interact with smart contracts
• Subscribe to network events
• Access account information and balances
• Retrieve historical transaction data

Who Should Use These APIs?

• dApp Developers: Building decentralized applications on IOST Layer 2
• Integration Engineers: Connecting existing systems to IOST blockchain
• Data Analysts: Extracting and analyzing on-chain data
• Smart Contract Developers: Testing and deploying contract functionality
• Wallet Providers: Managing user assets and transactions on IOST Layer 2

Available API Types

IOST Layer 2 offers four main API interfaces to meet different development requirements:

API Type	Primary Use Case	Description
JSON-RPC	Smart contract interaction	Ethereum-compatible interface for core blockchain operations
REST API	Data querying	HTTP endpoints for retrieving blockchain data
GraphQL	Complex data queries	Flexible query language for precise data retrieval
WebSocket	Real-time monitoring	Event-based subscription for monitoring chain activity

Each API type is designed to excel in specific use cases, giving developers the flexibility to choose the most suitable interface for their needs.

Key Features

• Ethereum Compatibility: All APIs follow Ethereum standards for seamless tool integration
• Low Latency: Optimized for high performance with minimal response times
• Comprehensive Coverage: Access to all blockchain data and functionality
• Developer Friendly: Well-documented interfaces with clear examples
• Robust Security: Secure access mechanisms with rate limiting to protect the network

Connection Information

API Endpoints

IOST Layer 2 provides the following API endpoints for different interfaces:

API Type	Mainnet Endpoint
JSON-RPC HTTP	https://l2-mainnet.iost.io
JSON-RPC WebSocket	wss://l2-mainnet.iost.io
REST API	https://l2-scan.iost.io/api-docs
GraphQL	https://l2-scan.iost.io/graphql

Basic Configuration

HTTP Headers

When making requests to the REST or JSON-RPC APIs via HTTP, include these headers:

Content-Type: application/json
Accept: application/json

Rate Limits

Public API access is subject to the following rate limits:

• JSON-RPC API: 10 requests per second per IP
• REST API: 20 requests per second per IP
• GraphQL API: 5 requests per second per IP
• WebSocket: 5 concurrent connections per IP

Connection Testing

You can verify your connection to the JSON-RPC API with a simple request:

curl -X POST https://l2-mainnet.iost.io \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xb6"  // Chain ID 182 in hexadecimal
}

Client Libraries

These popular libraries can be used to interact with IOST Layer 2 APIs:

• Web3.js: JavaScript library for Ethereum-compatible blockchains

npm install web3

• Ethers.js: Complete Ethereum wallet implementation and utilities

npm install ethers

• Apollo Client: For GraphQL API interactions

npm install @apollo/client graphql

Authentication & Access Control

IOST Layer 2 APIs are designed with a balance between accessibility and security. The authentication model varies by API type and usage patterns.

Public Access

Most API endpoints are publicly accessible for basic operations without requiring authentication:

• Standard blockchain queries
• Reading public contract data
• Retrieving transaction and block information
• Checking account balances

Public access is subject to the rate limits described in the Connection Information section.

Authentication Methods

While basic queries don't require authentication, certain operations may require different forms of authentication:

1. Transaction Signing

For state-changing operations (transactions), proper cryptographic signing is required:

• Transactions must be signed with the private key of the sending account
• Signatures verify the identity of the sender and authorize the transaction
• No API key is needed, but transaction signing proves ownership of the account

Example of signing a transaction with web3.js:

// Code example for transaction signing
const signedTx = await web3.eth.accounts.signTransaction(
  {
    to: recipientAddress,
    value: web3.utils.toWei('1', 'ether'),
    gas: 21000,
    gasPrice: await web3.eth.getGasPrice()
  },
  'your-private-key'
);

2. Read Contract Authentication

Some contracts may implement their own access control:

• Permissioned smart contracts may restrict data access based on caller address
• These restrictions are implemented at the contract level, not the API level
• Your transaction must come from an authorized address to access restricted functions

Security Recommendations

When working with IOST Layer 2 APIs, follow these security practices:

• Never embed private keys in client-side code or public repositories
• Use environment variables or secure key management systems to store sensitive credentials
• Implement proper error handling for failed authentication
• Consider using hardware wallets for production deployments
• Rotate any development keys regularly
• Use HTTPS for all API communications
• Validate all input and response data to prevent injection attacks

Authentication Errors

Common authentication-related errors you may encounter:

Error Code	Description	Solution
-32000	Invalid signature	Verify your signing key and transaction parameters
-32003	Transaction underpriced	Increase gas price to meet current network conditions
401	Unauthorized (REST API)	Verify your API key or credentials if using protected endpoints
429	Too Many Requests	Reduce request frequency or implement backoff strategy

By following these guidelines, you can ensure secure and reliable interaction with the IOST Layer 2 network while maintaining proper authentication practices.

API Usage Examples

Here are a few examples of how different API types can be used together in common scenarios:

Example 1: Building a Complete DApp Interaction

1. Use JSON-RPC API to connect user wallets and send transactions
2. Monitor transaction confirmation status in real-time via WebSocket API
3. Query historical transaction records with REST API
4. Utilize GraphQL API to fetch complex related data relationships

Example 2: Asset Management System

1. Use JSON-RPC API to check user balances and token holdings
2. Apply GraphQL API to analyze asset distribution and historical changes
3. Receive token transfer notifications through WebSocket API
4. Use REST API to get token pricing and market data

Next Steps: Exploring API Documentation

Now that you have an overview of the IOST Layer 2 API ecosystem, you can explore the detailed documentation for each API type based on your specific needs:

JSON-RPCEthereum-compatible interface for core blockchain operations and smart contractsREST APIHTTP endpoints for retrieving blockchain data through the block explorerGraphQLFlexible query language for precise and efficient data retrievalWebSocketEvent-based subscription system for real-time blockchain monitoring