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": "tnam1q...",
            "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": "tnam1q..."
}

Error Responses:

{
    "error": "Invalid Tendermint address",
    "details": "Tendermint address must be 40 hex characters"
}
{
    "error": "Not found",
    "details": "No validator found with Tendermint address CAFA..."
}

Get Validator Details

GET /api/pos/validators/{address}

Get detailed information about a specific validator.

address: Namada address of the validator

Success Response:

{
    "address": "tnam1q...",
    "state": "active",
    "stake": "1000000",
    "commission_rate": "0.05",
    "max_commission_change_per_epoch": "0.01",
    "metadata": {
        "email": "validator@example.com",
        "description": "Professional validator",
        "website": "https://example.com",
        "discord_handle": "validator#1234"
    }
}

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": [
        "tnam1q...",
        "tnam1q..."
    ]
}

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": "tnam1q...",
            "state": "active",
            "stake": "1000000",
            "commission_rate": "0.05",
            "max_commission_change_per_epoch": "0.01",
            "metadata": {
                "email": "validator@example.com",
                "description": "Professional validator",
                "website": "https://example.com",
                "discord_handle": "validator#1234"
            }
        }
    ],
    "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": "tnam1q...",
            "stake": "1000000"
        }
    ]
}

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": "tnam1q...",
            "stake": "1000000"
        }
    ]
}