Namada API Documentation

Health Endpoints

Basic Health Check

GET /api/health/api_status

Check if the API is running.

Response:

{
    "status": "ok",
    "version": "0.1.0"
}

RPC Health Check

GET /api/health/rpc_status

Check if the RPC connection is working.

Success Response:

{
    "status": "ok",
    "rpc_url": "https://rpc-1.namada.nodes.guru"
}

Error Response:

{
    "status": "error",
    "message": "RPC connection error: ...",
    "rpc_url": "https://rpc-1.namada.nodes.guru"
}

Proof of Stake Endpoints

Get Validator Liveness Information

GET /api/pos/liveness_info

Get liveness information for all validators.

Response:

{
    "liveness_window_len": 100,
    "liveness_threshold": "0.9",
    "validators": [
        {
            "native_address": "tnam1q...",
            "comet_address": "CAFAD8DA813BAE48779A4219A74632D5DCA49737",
            "missed_votes": 0
        }
    ]
}

Get Validator by Tendermint Address

GET /api/pos/validator_by_tm_addr/{tm_addr}

Get validator information by their Tendermint address.

tm_addr: Tendermint address of the validator (40 hex characters)

Success Response:

{
    "address": "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3"
}

Error Responses:

{
    "error": "Invalid Tendermint address format",
    "details": "Invalid Tendermint address format: INVALID. Expected 40 hex characters."
}
{
    "error": "Not found",
    "details": "No validator found with Tendermint address: CAFAD8DA813BAE48779A4219A74632D5DCA49737"
}

Get Validator Details

GET /api/pos/validator_details/{address}

Get detailed information about a specific validator.

address: Namada address of the validator

Success Response:

{
    "address": "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3",
    "state": "active",
    "stake": "1000000",
    "commission_rate": "0.05",
    "max_commission_change_per_epoch": "0.01",
    "metadata": {
        "email": "validator@example.com",
        "description": "Professional validator service",
        "website": "https://example.com",
        "discord_handle": "validator#1234",
        "name": "My Validator",
        "avatar": "https://example.com/avatar.png"
    }
}

Error Responses:

{
    "error": "Invalid address format",
    "details": "Invalid address format: expected bech32m encoding"
}
{
    "error": "Not found",
    "details": "Address tnam1q... is not a validator"
}

Get All Validators

GET /api/pos/validators

Get a simple list of all validators. This endpoint returns just the addresses without additional details.

Response:

{
    "validators": [
        "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3",
        "tnam1q9vhfdur7gadtwx4r223agpal0fpc0vjam8h8kgnv9c78k"
    ]
}

Get All Validators with Details

GET /api/pos/validators_details?page={page}&per_page={per_page}

Get detailed information about all validators with pagination.

page: Page number (default: 1, must be greater than 0)
per_page: Number of validators per page (default: 10, max: 50)

Success Response:

{
    "validators": [
        {
            "address": "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3",
            "state": "active",
            "stake": "1000000",
            "commission_rate": "0.05",
            "max_commission_change_per_epoch": "0.01",
            "metadata": {
                "email": "validator@example.com",
                "description": "Professional validator service",
                "website": "https://example.com",
                "discord_handle": "validator#1234",
                "name": "My Validator",
                "avatar": "https://example.com/avatar.png"
            }
        }
    ],
    "pagination": {
        "total": 100,
        "page": 1,
        "per_page": 10,
        "total_pages": 10
    }
}

Error Responses:

{
    "error": "Invalid pagination parameters",
    "details": "Page number must be greater than 0"
}
{
    "error": "Invalid pagination parameters",
    "details": "Items per page cannot exceed 50"
}
{
    "error": "Invalid pagination parameters",
    "details": "Page number 11 exceeds total pages 10"
}

Get Consensus Validator Set

GET /api/pos/validator_set/consensus

Get all validators in the consensus set with their bonded stake.

Response:

{
    "validators": [
        {
            "address": "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3",
            "stake": "1000000"
        },
        {
            "address": "tnam1q9vhfdur7gadtwx4r223agpal0fpc0vjam8h8kgnv9c78k",
            "stake": "950000"
        }
    ]
}

Get Below-Capacity Validator Set

GET /api/pos/validator_set/below_capacity

Get all validators in the below-capacity set with their bonded stake.

Response:

{
    "validators": [
        {
            "address": "tnam1q0snjs4eum5yjvkpm5xqpmy9dgnpf9hcldg2l3",
            "stake": "500000"
        }
    ]
}

Field Descriptions

Validator Metadata Fields

The metadata object in validator responses contains the following fields:

email: Validator's contact email (required)
description: Optional description of the validator service
website: Optional validator website URL
discord_handle: Optional Discord username for contact
name: Optional human-readable name for the validator
avatar: Optional validator avatar URL

Note: All fields except email are optional and may be null.

Error Handling

Common Error Response Format

All API errors follow this consistent format:

{
    "error": "Error type description",
    "details": "Specific error details (optional)"
}

Common HTTP Status Codes: