REST API

HTTP endpoints for querying Bitplanet blockchain state.

Overview

The REST API provides HTTP endpoints for querying:

• Account balances and information

• Staking validators and delegations

• Governance proposals and votes

• Distribution rewards

• Custom module state (Brahma, Precompile)

Default Endpoint: http://localhost:1317

Bank Module

Get All Balances

Get all token balances for an address.

Endpoint: GET /cosmos/bank/v1beta1/balances/{address}

curl http://localhost:1317/cosmos/bank/v1beta1/balances/cosmos1... | jq

Get Balance by Denomination

Get balance for a specific denomination.

Endpoint: GET /cosmos/bank/v1beta1/balances/{address}/by_denom

Query Parameters:

• denom: Token denomination (e.g., "bplcoin")

curl http://localhost:1317/cosmos/bank/v1beta1/balances/cosmos1.../by_denom?denom=bplcoin | jq

Get Total Supply

Get total supply of all tokens.

Endpoint: GET /cosmos/bank/v1beta1/supply

curl http://localhost:1317/cosmos/bank/v1beta1/supply | jq

Get Supply by Denomination

Get supply of a specific denomination.

Endpoint: GET /cosmos/bank/v1beta1/supply/by_denom

Query Parameters:

• denom: Token denomination

curl http://localhost:1317/cosmos/bank/v1beta1/supply/by_denom?denom=bplcoin | jq

Staking Module

Get All Validators

Get list of all validators.

Endpoint: GET /cosmos/staking/v1beta1/validators

curl http://localhost:1317/cosmos/staking/v1beta1/validators | jq

Get Validator by Address

Get validator information by operator address.

Endpoint: GET /cosmos/staking/v1beta1/validators/{validator_addr}

curl http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper1... | jq

Get Delegations for Delegator

Get all delegations for a delegator address.

Endpoint: GET /cosmos/staking/v1beta1/delegations/{delegator_addr}

curl http://localhost:1317/cosmos/staking/v1beta1/delegations/cosmos1... | jq

Get Delegations to Validator

Get all delegations to a specific validator.

Endpoint: GET /cosmos/staking/v1beta1/validators/{validator_addr}/delegations

curl http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper1.../delegations | jq

Get Staking Pool

Get current staking pool information.

Endpoint: GET /cosmos/staking/v1beta1/pool

curl http://localhost:1317/cosmos/staking/v1beta1/pool | jq

Get Staking Parameters

Get staking module parameters.

Endpoint: GET /cosmos/staking/v1beta1/params

curl http://localhost:1317/cosmos/staking/v1beta1/params | jq

Governance Module

Get All Proposals

Get list of all governance proposals.

Endpoint: GET /cosmos/gov/v1/proposals

curl http://localhost:1317/cosmos/gov/v1/proposals | jq

Get Proposal by ID

Get specific proposal details.

Endpoint: GET /cosmos/gov/v1/proposals/{proposal_id}

curl http://localhost:1317/cosmos/gov/v1/proposals/1 | jq

Get Votes for Proposal

Get all votes for a proposal.

Endpoint: GET /cosmos/gov/v1/proposals/{proposal_id}/votes

curl http://localhost:1317/cosmos/gov/v1/proposals/1/votes | jq

Get Deposits for Proposal

Get all deposits for a proposal.

Endpoint: GET /cosmos/gov/v1/proposals/{proposal_id}/deposits

curl http://localhost:1317/cosmos/gov/v1/proposals/1/deposits | jq

Get Governance Parameters

Get governance parameters by type.

Endpoint: GET /cosmos/gov/v1/params/{params_type}

Parameter Types:

• voting: Voting period parameters

• deposit: Deposit parameters

• tallying: Vote tallying parameters

curl http://localhost:1317/cosmos/gov/v1/params/voting | jq

Distribution Module

Get Delegator Rewards

Get all rewards for a delegator.

Endpoint: GET /cosmos/distribution/v1beta1/delegators/{delegator_addr}/rewards

curl http://localhost:1317/cosmos/distribution/v1beta1/delegators/cosmos1.../rewards | jq

Get Rewards from Specific Validator

Get rewards from a specific validator.

Endpoint: GET /cosmos/distribution/v1beta1/delegators/{delegator_addr}/rewards/{validator_addr}

curl http://localhost:1317/cosmos/distribution/v1beta1/delegators/cosmos1.../rewards/cosmosvaloper1... | jq

Get Validator Commission

Get commission earned by a validator.

Endpoint: GET /cosmos/distribution/v1beta1/validators/{validator_addr}/commission

curl http://localhost:1317/cosmos/distribution/v1beta1/validators/cosmosvaloper1.../commission | jq

Brahma Module

Brahma module endpoints are auto-generated from the gRPC service definitions.

Get Module Parameters

Get Brahma module parameters including siphon percentage and reward splits.

Endpoint: GET /bitplanet/brahma/params

curl http://localhost:1317/bitplanet/brahma/params | jq

Get AI Tensor by Block Height

Get contribution tensor for an AI at specific block height.

Endpoint: GET /bitplanet/brahma/ai-tensor/{aiId}/{blockHeight}

curl http://localhost:1317/bitplanet/brahma/ai-tensor/genie-ai/1000 | jq

Get Contribution by Wallet Address

Get specific contributor's contributions.

Endpoint: GET /bitplanet/brahma/contribution/{aiId}/{blockHeight}/{walletAddress}

curl http://localhost:1317/bitplanet/brahma/contribution/genie-ai/1000/0x123... | jq

Get Core Grant Application

Get Core Grant Application status by requester.

Endpoint: GET /bitplanet/brahma/core-grant-application/{requester}

curl http://localhost:1317/bitplanet/brahma/core-grant-application/cosmos1... | jq

Get Core Token Addresses

Get Core token contract addresses.

Endpoint: GET /bitplanet/brahma/core

curl http://localhost:1317/bitplanet/brahma/core | jq

Get AI Token Addresses

Get Gem token addresses for an AI.

Endpoint: GET /bitplanet/brahma/ai-tokens/{aiId}

curl http://localhost:1317/bitplanet/brahma/ai-tokens/genie-ai | jq

Get Claimable Rewards

Get claimable BPL rewards for an address.

Endpoint: GET /bitplanet/brahma/claimable-rewards/{address}

curl http://localhost:1317/bitplanet/brahma/claimable-rewards/0x123... | jq

Get Claim Statistics

Get aggregate statistics about pending claims and Core allocations.

Endpoint: GET /bitplanet/brahma/claim-statistics

curl http://localhost:1317/bitplanet/brahma/claim-statistics | jq

Precompile Module

Precompile module endpoints are auto-generated from the gRPC service definitions.

Get Precompile Parameters

Get precompile module parameters including contract addresses.

Endpoint: GET /bitplanet/precompile/params

curl http://localhost:1317/bitplanet/precompile/params | jq

Transaction Submission

Submit Transaction

Submit a signed transaction.

Endpoint: POST /cosmos/tx/v1beta1/txs

Request Body:

{
  "tx_bytes": "base64_encoded_tx",
  "mode": "BROADCAST_MODE_SYNC"
}

Broadcast Modes:

• BROADCAST_MODE_SYNC: Return after CheckTx

• BROADCAST_MODE_ASYNC: Return immediately

• BROADCAST_MODE_BLOCK: Wait for commit (deprecated)

curl -X POST http://localhost:1317/cosmos/tx/v1beta1/txs \
  -H "Content-Type: application/json" \
  -d '{
    "tx_bytes":"...",
    "mode":"BROADCAST_MODE_SYNC"
  }'

---

Related: gRPC API Reference | CLI Reference