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:

[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:

[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

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

# 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

Trusted community RPC nodes:

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

Latest list:

curl https://raw.githubusercontent.com/akash-network/net/main/mainnet/rpc-nodes.txt

Swagger/OpenAPI Documentation

Enable Swagger UI:

[api]
swagger = true

Access Swagger:

http://localhost:1317/swagger/

OpenAPI spec:

Akash API Swagger

API Architecture

gRPC API

Why gRPC?

Service Types

gRPC Query Services

Cosmos SDK Queries

Akash Module Queries

gRPC Client Examples

Query Providers

Query Specific Deployment

REST API (gRPC-Gateway)

REST Endpoints

Cosmos SDK REST Endpoints

Akash REST Endpoints

REST Examples

Query Account Balance

Query Providers

Submit Transactions

Via gRPC

Via REST

CometBFT RPC

Common RPC Endpoints

RPC Examples

Check Node Status

Get Block by Height

WebSocket Subscriptions

Subscribe to Events

WebSocket Example

API Configuration

gRPC Configuration

REST Configuration

RPC Configuration

Security Considerations

Production API Setup

Public RPC Nodes

Swagger/OpenAPI Documentation

Additional Resources