Sei Cosmos REST API Reference

Sei's Cosmos SDK layer provides native blockchain functionality through REST API endpoints. Access staking, governance, bank transfers, and CosmWasm contracts using familiar HTTP methods.

Base URL

https://api.blockeden.xyz/sei/<your-api-key>/cosmos/

Authentication

Include your API key in the URL path:

https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/bank/v1beta1/balances/sei1abc...

Bank Module

Get Account Balances

Get all token balances for an account.

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/bank/v1beta1/balances/sei1abc123def456ghi789

Response:

{
  "balances": [
    {
      "denom": "usei",
      "amount": "1000000000"
    },
    {
      "denom": "factory/sei1abc.../token",
      "amount": "500000000"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "2"
  }
}

Get Specific Token Balance

Get balance for a specific denomination.

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

Parameters:

• denom (query) - Token denomination (e.g., "usei")

curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/bank/v1beta1/balances/sei1abc123def456ghi789/by_denom?denom=usei"

Response:

{
  "balance": {
    "denom": "usei",
    "amount": "1000000000"
  }
}

Get Total Supply

Get total supply of all tokens.

Endpoint: GET /cosmos/bank/v1beta1/supply

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/bank/v1beta1/supply

Response:

{
  "supply": [
    {
      "denom": "usei",
      "amount": "10000000000000000"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "1"
  }
}

Get Supply by Denomination

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

Parameters:

• denom (query) - Token denomination

curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/bank/v1beta1/supply/by_denom?denom=usei"

Get Bank Parameters

Endpoint: GET /cosmos/bank/v1beta1/params

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/bank/v1beta1/params

Staking Module

Get All Validators

Get list of all validators.

Endpoint: GET /cosmos/staking/v1beta1/validators

Parameters:

• status (query) - Validator status: "BOND_STATUS_BONDED", "BOND_STATUS_UNBONDED", "BOND_STATUS_UNBONDING"
• pagination.limit (query) - Number of results per page
• pagination.offset (query) - Offset for pagination

curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/staking/v1beta1/validators?status=BOND_STATUS_BONDED&pagination.limit=10"

Response:

{
  "validators": [
    {
      "operator_address": "seivaloper1abc123def456ghi789",
      "consensus_pubkey": {
        "@type": "/cosmos.crypto.ed25519.PubKey",
        "key": "abc123def456..."
      },
      "jailed": false,
      "status": "BOND_STATUS_BONDED",
      "tokens": "1000000000000",
      "delegator_shares": "1000000000000.000000000000000000",
      "description": {
        "moniker": "Validator Name",
        "identity": "",
        "website": "https://validator.com",
        "security_contact": "",
        "details": "Validator description"
      },
      "unbonding_height": "0",
      "unbonding_time": "1970-01-01T00:00:00Z",
      "commission": {
        "commission_rates": {
          "rate": "0.100000000000000000",
          "max_rate": "0.200000000000000000",
          "max_change_rate": "0.010000000000000000"
        },
        "update_time": "2023-01-01T00:00:00Z"
      },
      "min_self_delegation": "1"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "100"
  }
}

Get Validator Details

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/staking/v1beta1/validators/seivaloper1abc123def456ghi789

Get Delegations for Delegator

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/staking/v1beta1/delegations/sei1abc123def456ghi789

Response:

{
  "delegation_responses": [
    {
      "delegation": {
        "delegator_address": "sei1abc123def456ghi789",
        "validator_address": "seivaloper1abc123def456ghi789",
        "shares": "1000000000.000000000000000000"
      },
      "balance": {
        "denom": "usei",
        "amount": "1000000000"
      }
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "1"
  }
}

Get Unbonding Delegations

Endpoint: GET /cosmos/staking/v1beta1/delegators/{delegator_addr}/unbonding_delegations

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/staking/v1beta1/delegators/sei1abc123def456ghi789/unbonding_delegations

Get Staking Pool

Endpoint: GET /cosmos/staking/v1beta1/pool

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/staking/v1beta1/pool

Response:

{
  "pool": {
    "not_bonded_tokens": "1000000000000",
    "bonded_tokens": "9000000000000"
  }
}

Get Staking Parameters

Endpoint: GET /cosmos/staking/v1beta1/params

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/staking/v1beta1/params

Distribution Module

Get Delegation Rewards

Get rewards for a specific delegation.

Endpoint: GET /cosmos/distribution/v1beta1/delegators/{delegator_address}/rewards/{validator_address}

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/distribution/v1beta1/delegators/sei1abc123def456ghi789/rewards/seivaloper1abc123def456ghi789

Response:

{
  "rewards": [
    {
      "denom": "usei",
      "amount": "123456789.123456789123456789"
    }
  ]
}

Get Total Rewards

Get total rewards for a delegator.

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/distribution/v1beta1/delegators/sei1abc123def456ghi789/rewards

Get Validator Commission

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/distribution/v1beta1/validators/seivaloper1abc123def456ghi789/commission

Get Community Pool

Endpoint: GET /cosmos/distribution/v1beta1/community_pool

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/distribution/v1beta1/community_pool

Governance Module

Get All Proposals

Get list of governance proposals.

Endpoint: GET /cosmos/gov/v1beta1/proposals

Parameters:

• proposal_status (query) - Filter by status: "PROPOSAL_STATUS_VOTING_PERIOD", "PROPOSAL_STATUS_PASSED", etc.
• voter (query) - Filter by voter address
• depositor (query) - Filter by depositor address

curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/gov/v1beta1/proposals?proposal_status=PROPOSAL_STATUS_VOTING_PERIOD"

Response:

{
  "proposals": [
    {
      "proposal_id": "1",
      "content": {
        "@type": "/cosmos.gov.v1beta1.TextProposal",
        "title": "Proposal Title",
        "description": "Proposal description"
      },
      "status": "PROPOSAL_STATUS_VOTING_PERIOD",
      "final_tally_result": {
        "yes": "0",
        "abstain": "0",
        "no": "0",
        "no_with_veto": "0"
      },
      "submit_time": "2023-01-01T00:00:00Z",
      "deposit_end_time": "2023-01-15T00:00:00Z",
      "total_deposit": [
        {
          "denom": "usei",
          "amount": "10000000000"
        }
      ],
      "voting_start_time": "2023-01-01T00:00:00Z",
      "voting_end_time": "2023-01-08T00:00:00Z"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "1"
  }
}

Get Proposal Details

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/gov/v1beta1/proposals/1

Get Proposal Votes

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/gov/v1beta1/proposals/1/votes

Get Specific Vote

Endpoint: GET /cosmos/gov/v1beta1/proposals/{proposal_id}/votes/{voter}

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/gov/v1beta1/proposals/1/votes/sei1abc123def456ghi789

Get Proposal Deposits

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/gov/v1beta1/proposals/1/deposits

Get Governance Parameters

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

Parameters:

• params_type - Type of parameters: "voting", "tallying", "deposit"

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/gov/v1beta1/params/voting

Auth Module

Get Account Information

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

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/auth/v1beta1/accounts/sei1abc123def456ghi789

Response:

{
  "account": {
    "@type": "/cosmos.auth.v1beta1.BaseAccount",
    "address": "sei1abc123def456ghi789",
    "pub_key": null,
    "account_number": "12345",
    "sequence": "0"
  }
}

Get All Accounts

Endpoint: GET /cosmos/auth/v1beta1/accounts

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/auth/v1beta1/accounts

Get Auth Parameters

Endpoint: GET /cosmos/auth/v1beta1/params

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmos/auth/v1beta1/params

CosmWasm Module

Get All Contracts

Get list of all smart contracts.

Endpoint: GET /cosmwasm/wasm/v1/contract

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/contract

Get Contract Info

Endpoint: GET /cosmwasm/wasm/v1/contract/{address}

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/contract/sei1contractaddress123

Response:

{
  "address": "sei1contractaddress123",
  "contract_info": {
    "code_id": "1",
    "creator": "sei1abc123def456ghi789",
    "admin": "sei1abc123def456ghi789",
    "label": "My Contract",
    "created": {
      "block_height": "12345",
      "tx_index": "0"
    },
    "ibc_port_id": "",
    "extension": null
  }
}

Query Contract State

Endpoint: GET /cosmwasm/wasm/v1/contract/{address}/smart

Parameters:

• query_msg (query) - Base64-encoded query message

# Query contract with a simple message
curl -X GET "https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/contract/sei1contractaddress123/smart" \
  -G -d 'query_msg=eyJnZXRfY29uZmlnIjp7fX0='

Example Query Message (before base64 encoding):

{"get_config":{}}

Get Contract History

Endpoint: GET /cosmwasm/wasm/v1/contract/{address}/history

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/contract/sei1contractaddress123/history

Get Contract Raw State

Endpoint: GET /cosmwasm/wasm/v1/contract/{address}/raw/{query_data}

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/contract/sei1contractaddress123/raw/636f6e666967

Get Code Info

Endpoint: GET /cosmwasm/wasm/v1/code/{code_id}

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/code/1

Get All Codes

Endpoint: GET /cosmwasm/wasm/v1/code

curl -X GET https://api.blockeden.xyz/sei/<your-api-key>/cosmwasm/wasm/v1/code

Tendermint RPC

Access Tendermint consensus layer information.

Base URL: https://sei-mainnet.blockeden.xyz/<your-api-key>/tm

Get Node Status

curl -X POST https://api.blockeden.xyz/sei/<your-api-key>/tm \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "status",
    "params": [],
    "id": 1
  }'

Get Block Information

curl -X POST https://api.blockeden.xyz/sei/<your-api-key>/tm \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "block",
    "params": ["12345"],
    "id": 1
  }'

Get Validators

curl -X POST https://api.blockeden.xyz/sei/<your-api-key>/tm \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "validators",
    "params": [],
    "id": 1
  }'

Error Handling

HTTP Status Codes

• 200: Success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (invalid API key)
• 404: Not Found (resource doesn't exist)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error

Common Error Response Format

{
  "code": 3,
  "message": "account sei1abc123def456ghi789 not found",
  "details": []
}

Pagination

Most list endpoints support pagination:

Parameters:

• pagination.key - Key for next page
• pagination.offset - Number of items to skip
• pagination.limit - Number of items per page (default: 100, max: 1000)
• pagination.count_total - Include total count in response
• pagination.reverse - Reverse the order

Example:

curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/staking/v1beta1/validators?pagination.limit=50&pagination.offset=100"

Rate Limits

• Free Tier: 100 requests/second
• Pro Tier: 1,000 requests/second
• Enterprise: Custom limits

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Best Practices

1. Use Pagination

Always paginate large result sets:

# Good - paginated request
curl -X GET "https://sei-mainnet.blockeden.xyz/<your-api-key>/cosmos/staking/v1beta1/validators?pagination.limit=100"

# Avoid - requesting all validators at once without pagination

2. Cache Responses

Cache static data like validator information:

// Cache validator list for 5 minutes
const cacheKey = 'validators';
const cachedValidators = cache.get(cacheKey);
if (!cachedValidators) {
  const validators = await fetch('/cosmos/staking/v1beta1/validators');
  cache.set(cacheKey, validators, 300); // 5 minutes
}

3. Handle Errors Gracefully

async function getBalance(address) {
  try {
    const response = await fetch(`/cosmos/bank/v1beta1/balances/${address}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Failed to fetch balance:', error);
    return null;
  }
}

Next Steps

• Learn about Sei WebSocket Guide for real-time data
• Check out Sei JSON-RPC API for EVM functionality
• Visit BlockEden.xyz Dashboard to monitor usage

Resources

• Cosmos SDK REST Documentation
• Sei Official Documentation
• CosmWasm Documentation
• Tendermint RPC Documentation