API Layer

The API Layer provides interfaces for querying blockchain state and submitting transactions. Akash nodes expose three types of APIs: gRPC (primary), REST (gRPC-Gateway), and CometBFT RPC.

API Architecture

+---------------------------------------------------------------+
|                        API Layer                              |
|                                                               |
|  +-----------------+  +-----------------+  +----------------+ |
|  |     gRPC        |  |      REST       |  |   CometBFT     | |
|  |   (Port 9090)   |  |   (Port 1317)   |  |      RPC       | |
|  |                 |  |                 |  |  (Port 26657)  | |
|  |  Native Binary  |  |  HTTP Gateway   |  |                | |
|  |  Protocol Buf   |  | (gRPC-Gateway)  |  |  Blockchain    | |
|  |  Streaming      |  |   JSON/HTTP     |  |    Queries     | |
|  +-----------------+  +-----------------+  +----------------+ |
|          |                    |                    |          |
|          +--------------------+--------------------+          |
|                               |                               |
+---------------------------------------------------------------+
                                |
                       Application State
                    (Keepers & State Store)

gRPC API

gRPC is the primary API for querying state and submitting transactions.

Why gRPC?

Advantages:

  • High Performance - Binary protocol (Protocol Buffers)
  • Type Safety - Strong typing via protobuf
  • Streaming - Real-time updates
  • Code Generation - Auto-generate clients
  • HTTP/2 - Multiplexing, compression

Default Port: 9090

Service Types

1. Query Services - Read-only state queries 2. Msg Services - Submit transactions 3. Reflection Services - Service discovery

gRPC Query Services

Cosmos SDK Queries

Auth Module:

/cosmos.auth.v1beta1.Query/Account
/cosmos.auth.v1beta1.Query/Accounts
/cosmos.auth.v1beta1.Query/AccountInfo
/cosmos.auth.v1beta1.Query/Params

Bank Module:

/cosmos.bank.v1beta1.Query/Balance
/cosmos.bank.v1beta1.Query/AllBalances
/cosmos.bank.v1beta1.Query/TotalSupply
/cosmos.bank.v1beta1.Query/SupplyOf
/cosmos.bank.v1beta1.Query/DenomMetadata

Staking Module:

/cosmos.staking.v1beta1.Query/Validators
/cosmos.staking.v1beta1.Query/Validator
/cosmos.staking.v1beta1.Query/Delegation
/cosmos.staking.v1beta1.Query/Delegations
/cosmos.staking.v1beta1.Query/UnbondingDelegation
/cosmos.staking.v1beta1.Query/Pool

Distribution Module:

/cosmos.distribution.v1beta1.Query/Rewards
/cosmos.distribution.v1beta1.Query/DelegationTotalRewards
/cosmos.distribution.v1beta1.Query/ValidatorCommission
/cosmos.distribution.v1beta1.Query/CommunityPool

Gov Module:

/cosmos.gov.v1.Query/Proposal
/cosmos.gov.v1.Query/Proposals
/cosmos.gov.v1.Query/Vote
/cosmos.gov.v1.Query/Votes
/cosmos.gov.v1.Query/Params
/cosmos.gov.v1.Query/Deposits

Akash Module Queries

Deployment Module:

/akash.deployment.v1.Query/Deployments
/akash.deployment.v1.Query/Deployment
/akash.deployment.v1.Query/Group

Market Module:

/akash.market.v1.Query/Orders
/akash.market.v1.Query/Order
/akash.market.v1.Query/Bids
/akash.market.v1.Query/Bid
/akash.market.v1.Query/Leases
/akash.market.v1.Query/Lease

Provider Module:

/akash.provider.v1.Query/Providers
/akash.provider.v1.Query/Provider

Audit Module:

/akash.audit.v1.Query/AllProvidersAttributes
/akash.audit.v1.Query/ProviderAttributes
/akash.audit.v1.Query/ProviderAuditorAttributes
/akash.audit.v1.Query/AuditorAttributes

Cert Module:

/akash.cert.v1.Query/Certificates

Escrow Module:

/akash.escrow.v1.Query/Accounts
/akash.escrow.v1.Query/Payments

gRPC Client Examples

Query Providers

# Using grpcurl (install: go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest)
grpcurl -plaintext localhost:9090 \
  akash.provider.v1.Query/Providers

Query Specific Deployment

grpcurl -plaintext \
  -d '{
    "id": {
      "owner": "akash1...",
      "dseq": "123"
    }
  }' \
  localhost:9090 \
  akash.deployment.v1.Query/Deployment

REST API (gRPC-Gateway)

REST API is automatically generated from gRPC services using gRPC-Gateway.

Default Port: 1317

Enable REST API:

app.toml
[api]
enable = true
address = "tcp://0.0.0.0:1317"

REST Endpoints

Format:

GET  /akash/{module}/{version}/{resource}
POST /cosmos/tx/v1beta1/txs

Cosmos SDK REST Endpoints

Auth:

GET /cosmos/auth/v1beta1/accounts/{address}
GET /cosmos/auth/v1beta1/accounts

Bank:

GET /cosmos/bank/v1beta1/balances/{address}
GET /cosmos/bank/v1beta1/balances/{address}/by_denom
GET /cosmos/bank/v1beta1/supply

Staking:

GET /cosmos/staking/v1beta1/validators
GET /cosmos/staking/v1beta1/validators/{validator_addr}
GET /cosmos/staking/v1beta1/delegations/{delegator_addr}
GET /cosmos/staking/v1beta1/validators/{validator_addr}/delegations

Gov:

GET /cosmos/gov/v1/proposals
GET /cosmos/gov/v1/proposals/{proposal_id}
GET /cosmos/gov/v1/proposals/{proposal_id}/votes
GET /cosmos/gov/v1/proposals/{proposal_id}/deposits

Akash REST Endpoints

Deployment:

GET /akash/deployment/v1/deployments/list
GET /akash/deployment/v1/deployments/info
  ?id.owner={owner}&id.dseq={dseq}

Market:

GET /akash/market/v1/orders/list
GET /akash/market/v1/orders/info
  ?id.owner={owner}&id.dseq={dseq}&id.gseq={gseq}&id.oseq={oseq}


GET /akash/market/v1/bids/list
GET /akash/market/v1/leases/list

Provider:

GET /akash/provider/v1/providers
GET /akash/provider/v1/providers/{owner}

Audit:

GET /akash/audit/v1/attributes/list

REST Examples

Query Account Balance

curl http://localhost:1317/cosmos/bank/v1beta1/balances/akash1...

Response:

{
  "balances": [
    {
      "denom": "uakt",
      "amount": "1000000000"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "1"
  }
}

Query Providers

curl "http://localhost:1317/akash/provider/v1/providers"

Submit Transactions

Via gRPC

1. Build transaction:

msg := &deploymenttypes.MsgCreateDeployment{
    Id: deploymenttypes.DeploymentID{
        Owner: owner,
        Dseq:  dseq,
    },
    Groups: groups,
    Version: version,
    Deposit: deposit,
}


txBuilder := txConfig.NewTxBuilder()
txBuilder.SetMsgs(msg)
txBuilder.SetGasLimit(200000)
txBuilder.SetFeeAmount(sdk.NewCoins(
    sdk.NewCoin("uakt", sdk.NewInt(5000)),
))

2. Sign transaction:

signerData := authsigning.SignerData{
    ChainID:       chainID,
    AccountNumber: accNum,
    Sequence:      seq,
}


sigV2, err := tx.SignWithPrivKey(
    txConfig.SignModeHandler(),
    signerData,
    txBuilder,
    privKey,
    txConfig,
    seq,
)

3. Broadcast:

txBytes, err := txConfig.TxEncoder()(txBuilder.GetTx())


broadcastReq := &txtypes.BroadcastTxRequest{
    TxBytes: txBytes,
    Mode:    txtypes.BroadcastMode_BROADCAST_MODE_SYNC,
}


client := txtypes.NewServiceClient(conn)
res, err := client.BroadcastTx(ctx, broadcastReq)

Via REST

Endpoint:

POST /cosmos/tx/v1beta1/txs

Request body:

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

Broadcast modes:

  • BROADCAST_MODE_SYNC - Wait for CheckTx
  • BROADCAST_MODE_ASYNC - Return immediately
  • BROADCAST_MODE_BLOCK - Wait for block inclusion (deprecated)

CometBFT RPC

Low-level blockchain queries via CometBFT RPC.

Default Port: 26657

Enable RPC:

config.toml
[rpc]
laddr = "tcp://0.0.0.0:26657"

Common RPC Endpoints

Node Status:

GET /status

Response:

{
  "node_info": {
    "protocol_version": {...},
    "id": "node_id",
    "network": "akashnet-2",
    "version": "0.38.0"
  },
  "sync_info": {
    "latest_block_hash": "ABC123...",
    "latest_block_height": "12345678",
    "latest_block_time": "2024-01-01T00:00:00Z",
    "catching_up": false
  },
  "validator_info": {
    "address": "validator_address",
    "pub_key": {...},
    "voting_power": "1000000"
  }
}

Get Block:

GET /block?height=12345

Get Block by Hash:

GET /block_by_hash?hash=0x...

Get Latest Block:

GET /block

Get Blockchain Info:

GET /blockchain?minHeight=1&maxHeight=100

Get Transaction:

GET /tx?hash=0x...&prove=true

Search Transactions:

GET /tx_search?query="tx.height>1000"&prove=false

Get Validators:

GET /validators?height=12345

Get Consensus State:

GET /consensus_state

Get Net Info:

GET /net_info

Get Genesis:

GET /genesis

RPC Examples

Check Node Status

curl http://localhost:26657/status | jq

Get Block by Height

curl "http://localhost:26657/block?height=12345" | jq

WebSocket Subscriptions

Subscribe to real-time blockchain events.

Endpoint:

ws://localhost:26657/websocket

Subscribe to Events

New blocks:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "query": "tm.event='NewBlock'"
  },
  "id": 1
}

New transactions:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "query": "tm.event='Tx'"
  },
  "id": 2
}

Custom events:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "query": "akash.v1.EventLeaseCreated.id.owner='akash1...'"
  },
  "id": 3
}

WebSocket Example

# Using websocat (install: cargo install websocat)
echo '{"jsonrpc":"2.0","method":"subscribe","params":{"query":"tm.event='\''NewBlock'\''"},"id":1}' | \
  websocat ws://localhost:26657/websocket

API Configuration

gRPC Configuration

app.toml:

[grpc]
enable = true
address = "0.0.0.0:9090"

REST Configuration

app.toml:

[api]
enable = true
address = "tcp://0.0.0.0:1317"
swagger = true
enabled-unsafe-cors = false

RPC Configuration

config.toml:

[rpc]
laddr = "tcp://0.0.0.0:26657"


# Maximum number of simultaneous connections
max_open_connections = 900


# Maximum number of subscription clients
max_subscription_clients = 100


# CORS allowed origins
cors_allowed_origins = []

Security Considerations

Production API Setup

1. Use Reverse Proxy

server {
  listen 443 ssl;
  server_name api.example.com;


  location / {
    proxy_pass http://localhost:1317;
  }
}

2. Rate Limiting

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;


location / {
  limit_req zone=api burst=20;
  proxy_pass http://localhost:1317;
}

3. Authentication

Add API keys or OAuth for public endpoints.

4. CORS Configuration

[api]
enabled-unsafe-cors = false  # Disable in production

5. Firewall Rules

Terminal window
# Only allow from specific IPs
ufw allow from 1.2.3.4 to any port 9090
ufw allow from 1.2.3.4 to any port 1317

Public RPC Nodes

Examples of community RPC endpoints (for illustration; the canonical list lives in repo metadata):

https://rpc.akashnet.net:443
https://rpc.akash.forbole.com:443
https://rpc-akash.ecostake.com:443
https://akash-rpc.polkachu.com:443
https://akash.c29r3.xyz:443/rpc

Current RPC URLs (from meta.json):

Terminal window
curl -sSf https://raw.githubusercontent.com/akash-network/net/main/mainnet/meta.json | jq -r '.apis.rpc[].address'

(Public RPC endpoints are listed under apis.rpc in meta.json.)

Swagger/OpenAPI Documentation

Enable Swagger UI:

[api]
swagger = true

Access Swagger:

http://localhost:1317/swagger/

OpenAPI spec:

Additional Resources

Edit page on github
Application Layer Hermes Relayer