Getting Started with the Public API

Welcome to the Public API documentation. This API provides access to real-time blockchain data and network statistics directly from our nodes.

The Public API is split up into three main parts:

  • The regular "Public API" - this provides access to the blockchain data for general use.
  • The "Transaction API" - this is focused on the transaction pool of the node it's running on, and is used to POST transactions to the network.
  • The "EVM API" - this is focused on the Ethereum Virtual Machine (EVM) that is running on the node, and is used to interact with the underlying JSON RPC.

With a stock Mainsail installation, each of these APIs will run on separate ports. The Public API will run on port 4003, the Transaction API will run on port 4007, and the EVM API will run on port 4008.

Request Headers

All requests must include:

Content-Type: application/json

Requests without this header will be rejected or return malformed responses.

Authentication & Rate Limits

The API is publicly accessible and does not require authentication for any of its endpoints. The API does enforce rate limits to ensure fair usage. Rate limits are applied per IP address. Headers included in responses:

  • X-RateLimit-Limit: Total requests allowed per hour
  • X-RateLimit-Remaining: Remaining requests for the hour
  • X-RateLimit-Reset: Time when the limit resets (Unix timestamp)

API Environments

We provide public API servers for testing and development purposes:

Production Environment:

  • Base URL: https://api.ark.io/api
  • Status: Production-ready, fully synchronized

Development Environment:

  • Base URL: https://dapi.ark.io/api
  • Status: Latest features, may be unstable

Pagination

Results are paginated with the following defaults and limits:

  • Default page size: 100 items
  • Maximum page size: 100 items
  • Page selection: Use ?page=<number>
  • Custom page size: Use ?limit=<number>

Example:

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

Error Handling

The API uses standard HTTP response codes:

  • 200: Success
  • 400: Bad Request
  • 404: Not Found
  • 422: Unprocessable Entity
  • 429: Too Many Requests
  • 500: Internal Server Error

Error responses include detailed messages:

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "\"unsupported\" is not allowed"
}

Node Synchronization

Each API node maintains its own blockchain state. Therefore always be aware that nodes may occasionally:

  • Fork from the main chain
  • Fall out of sync
  • Experience temporary delays

Monitor your node's health by comparing responses with other public nodes or our official block explorer at https://live.arkscan.io for Mainnet and https://test.arkscan.io for Testnet.

SDK Support

Official SDKs are available for:

  • Go
  • Java
  • PHP
  • Python
  • TypeScript

SDKs provide a more convenient way to interact with the API. An example initialisation can be found below. For more information, refer to the respective SDK documentation.

import "github.com/ArkEcosystem/go-client/client"

hosts := client.Hosts{
	API:          "https://testnet.mainsailhq.com/api",
	Transactions: "https://testnet.mainsailhq.com/tx/api",
	EVM:          "https://testnet.mainsailhq.com/rpc",
}

client := client.NewClient(nil, hosts)