API Documentation - Verdix | The Green Future of Cryptocurrency

Introduction

The Verdix v7.46 API provides a RESTful interface to interact with the Verdix blockchain. All responses are returned in JSON format with UTF-8 encoding.

Base URL

All API endpoints are relative to: http://localhost:8080/api

Quick Example

cURL

curl -X GET "http://localhost:8080/api/chain/info"

Response

{
  "height": 12345,
  "tip": "a1b2c3d4e5f6...",
  "current_slot": 12348,
  "slot_mod": 0,
  "total_tx": 5678,
  "genesis_time": 1704067200,
  "is_genesis": false,
  "sync_complete": true,
  "pending_blocks": 0,
  "last_block_time": "2024-01-01T12:00:00Z"
}

Authentication

The Verdix API is currently public and does not require authentication. All endpoints are accessible without an API key.

Future Updates

Administrative endpoints may require authentication in future versions.

Rate Limits

To ensure fair usage and system stability, the API implements rate limiting:

Limit Type	Value	Window
Requests per IP	`100`	Per minute
Requests per IP	`1000`	Per hour

Exceeding these limits returns 429 Too Many Requests.

Error Handling

All errors return a JSON object with an error field:

Error Response

{
  "error": "block not found"
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request successful
`400`	Bad Request	Invalid parameters or malformed request
`404`	Not Found	Resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error
`503`	Service Unavailable	Pipeline not initialized

Get Chain Info

GET /api/chain/info

Returns current blockchain information including height, slot, and sync status.

Response

ChainInfo

{
  "height": 12345,
  "tip": "a1b2c3d4e5f6789...",
  "current_slot": 12348,
  "slot_mod": 0,
  "total_tx": 5678,
  "genesis_time": 1704067200,
  "is_genesis": false,
  "sync_complete": true,
  "pending_blocks": 0,
  "last_block_time": "2024-01-01T12:00:00Z"
}

Response Fields

Field	Type	Description
`height`	uint64	Current chain height
`tip`	string	Latest block hash (64 hex chars)
`current_slot`	uint64	Current global slot number
`slot_mod`	uint8	Slot within minute (0-3)
`total_tx`	uint64	Total transactions processed
`genesis_time`	int64	Genesis timestamp (Unix)
`is_genesis`	bool	True if in genesis mode (first 4 slots)
`sync_complete`	bool	True if node is synced
`pending_blocks`	int	Blocks waiting to commit
`last_block_time`	string	Last block timestamp (ISO 8601)

Get Blocks

GET /api/chain/blocks

Returns multiple blocks. Supports pagination via query parameters.

Query Parameters

Parameter	Type	Default	Description
`limit`	int	10	Number of recent blocks (max 100)
`from`	uint64	0	Start height (inclusive)
`to`	uint64	tip	End height (inclusive)

Example

cURL

# Get last 20 blocks
curl "http://localhost:8080/api/chain/blocks?limit=20"

# Get blocks from height 100 to 150
curl "http://localhost:8080/api/chain/blocks?from=100&to=150"

Response

Block[]

[
  {
    "header": {
      "height": 12345,
      "slot": 12348,
      "slot_mod": 0,
      "timestamp": 1704067200,
      "prev_hash": "...",
      "tx_root": "...",
      "state_root": "...",
      "vrf_score": "...",
      "vrf_proof": "...",
      "producer_id": "seed1"
    },
    "transactions": [...],
    "signature": "...",
    "commit_time": 1704067215
  },
  ...
]

Get Block by Height

GET /api/chain/block/{height}

Returns a single block by its height.

Path Parameters

Parameter	Type	Description
`height`	uint64	Block height

Example

cURL

curl "http://localhost:8080/api/chain/block/100"

Errors

`400`	Invalid height format
`404`	Block not found

Get Block by Hash

GET /api/chain/block/hash/{hash}

Returns a single block by its hash.

Path Parameters

Parameter	Type	Description
`hash`	string	Block hash (64 hex characters)

Example

cURL

curl "http://localhost:8080/api/chain/block/hash/a1b2c3d4..."

Get All Accounts

GET /api/accounts

Returns all accounts sorted by balance (descending).

Response

AccountState[]

[
  {
    "address": "verdix1a1b2c3d4e5f6789012345678901234abcd",
    "balance": 100000000000,
    "nonce": 5
  },
  {
    "address": "verdix1x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3",
    "balance": 50000000000,
    "nonce": 2
  },
  ...
]

Balance Unit

Balance is in satoshi (1 VDX = 100,000,000 satoshi)

Get Account Info

GET /api/account/{address}

Returns account information for a specific address.

Path Parameters

Parameter	Type	Description
`address`	string	Verdix address (41 characters, starts with `verdix1`)

Response

AccountState

{
  "address": "verdix1a1b2c3d4e5f6789012345678901234abcd",
  "balance": 100000000000,
  "nonce": 5
}

Response Fields

Field	Type	Description
`address`	string	Account address
`balance`	uint64	Balance in satoshi
`nonce`	uint64	Transaction count (for replay protection)

Non-existent Accounts

If account doesn't exist, returns balance: 0 and nonce: 0 (not 404)

Get Balance

GET /api/account/{address}/balance

Returns only the balance for an address (lightweight endpoint).

Response

JSON

{
  "balance": 100000000000
}

Submit Transaction

POST /api/tx/submit

Submits a new transaction to the mempool.

Request Body

Transaction

{
  "from": "verdix1sender...",
  "to": "verdix1receiver...",
  "amount": 100000000,
  "fee": 10000,
  "nonce": 1,
  "signature": "base64_encoded_signature..."
}

Request Fields

Field	Type	Required	Description
`from`	string	Yes	Sender address
`to`	string	Yes	Recipient address
`amount`	uint64	Yes	Amount in satoshi
`fee`	uint64	Yes	Transaction fee in satoshi
`nonce`	uint64	Yes	Sender's current nonce + 1
`signature`	bytes	Yes	Ed25519 signature (96 bytes: 64 sig + 32 pubkey)
`data`	bytes	No	Optional data payload

Success Response

JSON

{
  "status": "accepted",
  "txid": "a1b2c3d4e5f6789..."
}

Error Response

400 Bad Request

{
  "error": "insufficient balance"
}

Get Transaction

GET /api/tx/{txid}

Returns transaction details by ID. Checks mempool first, then committed blocks.

Path Parameters

Parameter	Type	Description
`txid`	string	Transaction ID (64 hex characters)

Response (Pending)

JSON

{
  "tx": {
    "id": "a1b2c3d4...",
    "type": "transfer",
    "from": "verdix1sender...",
    "to": "verdix1receiver...",
    "amount": 100000000,
    "fee": 10000,
    "nonce": 1,
    "timestamp": 1704067200,
    "signature": "..."
  },
  "status": "pending"
}

Get Mempool

GET /api/mempool

Returns all pending transactions in the mempool.

Response

JSON

{
  "count": 5,
  "transactions": [
    {
      "id": "a1b2c3d4...",
      "type": "transfer",
      "from": "verdix1...",
      "to": "verdix1...",
      "amount": 100000000,
      "fee": 10000,
      "nonce": 1,
      "timestamp": 1704067200
    },
    ...
  ]
}

Pipeline Status

GET /api/pipeline/status

Returns current N+3 pipeline status showing all phases.

Response

PipelineStatus

{
  "current_slot": 12348,
  "slot_mod": 0,
  "is_genesis": false,
  "sync_complete": true,
  "pending_blocks": 0,
  "phases": {
    "tx_collect": { "height": 12348, "status": "active" },
    "tx_consensus": { "height": 12347, "status": "completed" },
    "block_vrf": { "height": 12346, "status": "completed" },
    "commit": { "height": 12345, "status": "completed" }
  }
}

N+3 Pipeline Model

Phase	Height	Description
`TX_COLLECT`	H+3	Gathering transactions from mempool
`TX_CONSENSUS`	H+2	Nodes agree on common TX set
`BLOCK_VRF`	H+1	VRF determines block winner
`COMMIT`	H	Winning block written to chain

Current Slot

GET /api/pipeline/slot

Returns current slot information.

Response

JSON

{
  "slot": 12348,
  "slot_mod": 0,
  "height": 12345
}

Response Fields

Field	Type	Description
`slot`	uint64	Global slot number
`slot_mod`	uint8	Position within minute (0-3)
`height`	uint64	Expected chain height for this slot

Miner Statistics

GET /api/miners

Returns all block producers sorted by blocks mined (descending).

Response

MinerStats[]

[
  {
    "node_id": "seed1",
    "blocks_mined": 5000,
    "total_reward": 500000000000,
    "last_block": 12345,
    "address": "verdix1..."
  },
  {
    "node_id": "seed2",
    "blocks_mined": 4500,
    "total_reward": 450000000000,
    "last_block": 12344,
    "address": "verdix1..."
  },
  ...
]

Response Fields

Field	Type	Description
`node_id`	string	Node identifier
`blocks_mined`	uint64	Total blocks produced
`total_reward`	uint64	Total rewards earned (satoshi)
`last_block`	uint64	Height of last produced block
`address`	string	Miner's reward address

Network Statistics

GET /api/stats

Returns overall network statistics.

Response

NetworkStats

{
  "height": 12345,
  "total_blocks": 12345,
  "total_tx": 5678,
  "total_accounts": 234,
  "total_supply": 1234500000000,
  "circulating_supply": 1222155000000,
  "dev_fund_balance": 12345000000,
  "active_miners": 3
}

Response Fields

Field	Type	Description
`height`	uint64	Current chain height
`total_blocks`	uint64	Total blocks in chain
`total_tx`	uint64	Total transactions
`total_accounts`	int	Number of accounts with balance
`total_supply`	uint64	Total minted supply (satoshi)
`circulating_supply`	uint64	Supply minus dev fund
`dev_fund_balance`	uint64	Developer fund balance
`active_miners`	int	Number of active block producers

Health Check

GET /api/health

Returns node health status. Use for monitoring and load balancers.

Response

JSON

{
  "status": "healthy",
  "timestamp": 1704067200,
  "height": 12345
}

Block Structure

Complete block structure with header and transactions.

Block

{
  "header": {
    "height": 12345,           // Block height (uint64)
    "slot": 12348,             // Global slot number (uint64)
    "slot_mod": 0,             // Slot within minute 0-3 (uint8)
    "timestamp": 1704067200,   // Block timestamp (Unix)
    "prev_hash": "a1b2c3...",  // Previous block hash (64 hex)
    "tx_root": "d4e5f6...",    // Merkle root of transactions
    "state_root": "g7h8i9...", // State trie root
    "vrf_score": "...",        // VRF output (base64)
    "vrf_proof": "...",        // VRF proof (base64)
    "producer_id": "seed1"     // Block producer node ID
  },
  "transactions": [
    // Array of Transaction objects
  ],
  "signature": "...",          // Producer's Ed25519 signature (base64)
  "commit_time": 1704067215    // When block was committed (Unix)
}

Transaction Structure

Transaction format supporting transfers and coinbase rewards.

Transaction

{
  "id": "a1b2c3d4e5f6...",      // Transaction ID (64 hex)
  "type": "transfer",           // "transfer" | "coinbase" | "contract"
  "from": "verdix1sender...",   // Sender address
  "to": "verdix1receiver...",   // Recipient address
  "amount": 100000000,          // Amount in satoshi
  "fee": 10000,                 // Fee in satoshi
  "nonce": 1,                   // Sender's nonce
  "timestamp": 1704067200,      // Transaction timestamp
  "signature": "...",           // Ed25519 signature (96 bytes base64)
  "data": null,                 // Optional data payload
  "inputs": [],                 // UTXO inputs (optional)
  "outputs": []                 // UTXO outputs (optional)
}

Transaction Types

Type	Description
`transfer`	Standard value transfer between accounts
`coinbase`	Block reward transaction (from: "coinbase")
`contract`	Smart contract interaction (future)

Address Format

Verdix v7.46 uses a human-readable address format with built-in checksum.

verdix1 Prefix (7)

a1b2c3d4e5f6789012345678901234 Address Hash (30)

abcd Checksum (4)

Format Rules

Component	Length	Format
Prefix	7 chars	`verdix1` (fixed)
Address Hash	30 chars	Hexadecimal (SHA256 of pubkey)
Checksum	4 chars	Hexadecimal (SHA256²)
Total	41 chars

Example Address

Valid Address

verdix1a1b2c3d4e5f6789012345678901234abcd

Validation Regex

Pattern

^verdix1[a-fA-F0-9]{34}$