Home Docs Telegram Status

API Reference

Base URL: https://rpc.nodius.xyz

All authenticated endpoints require one of: X-Api-Key header, per-request wallet signature (v2) headers (X-Pubkey, X-Signature, X-Timestamp, X-Nonce), or Authorization: Bearer <session-token>. See Authentication.

POST / (RPC Endpoint)

The primary hot-node endpoint. It is optimized for low-latency account reads, recent-chain state, transaction sending, priority-fee helpers, WebSocket traffic, and Yellowstone lite streaming. Heavy indexed scans and archive/history methods are gated by endpoint profile and return deterministic no-charge errors when not enabled.

Also available at POST /rpc.

Request

POST /
Content-Type: application/json
X-Pubkey: <base58-pubkey>
X-Signature: <base58-signature>
X-Timestamp: <unix-timestamp>
X-Nonce: <hex-nonce>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlot",
  "params": []
}

Or with session token:

POST /
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlot",
  "params": []
}

Or with API key:

POST /
Content-Type: application/json
X-Api-Key: srpc_live_<base64url>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlot",
  "params": []
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Credits-Remaining: 9999
X-Request-Id: req_abc123

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 285943216
}

Batch Requests

Send an array of JSON-RPC requests:

[
  {"jsonrpc": "2.0", "id": 1, "method": "getSlot"},
  {"jsonrpc": "2.0", "id": 2, "method": "getBlockHeight"},
  {"jsonrpc": "2.0", "id": 3, "method": "getBalance", "params": ["vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"]}
]

Response is an array of results in the same order. Each method is billed individually. Maximum 20 requests per batch.

Supported Methods And Launch Profile

READ_CHEAP (1 credit)

getAccountInfo              getBalance                  getBlockCommitment
getBlockHeight              getBlockProduction          getBlockTime
getClusterNodes             getEpochInfo                getEpochSchedule
getFeeForMessage            getFirstAvailableBlock      getGenesisHash
getHealth                   getHighestSnapshotSlot      getIdentity
getInflationGovernor        getInflationRate            getInflationReward
getLatestBlockhash          getLeaderSchedule           getMaxRetransmitSlot
getMaxShredInsertSlot       getMinimumBalanceForRentExemption
getMultipleAccounts         getRecentPerformanceSamples getRecentPrioritizationFees
getSignatureStatuses        getSlot                     getSlotLeader
getSlotLeaders              getStakeActivation          getStakeMinimumDelegation
getSupply                   getTokenAccountBalance      getTokenAccountsByDelegate
getTokenAccountsByOwner     getTokenLargestAccounts     getTokenSupply
getTransactionCount         getVersion                  getVoteAccounts
isBlockhashValid            minimumLedgerSlot           getPriorityFeeEstimate
suggestPriorityFee

READ_MEDIUM (5 credits)

simulateTransaction                 getAssetsByOwner
getEnrichedTransaction              explainTransaction
getTokenAccountsByOwner             getTokenAccountsByDelegate

ARCHIVE_HISTORY (5-25 credits, profile-gated)

These methods are supported by the codebase and are enabled on archive/history endpoints. The Frankfurt hot-node launch endpoint returns -32004 without billing when this profile is disabled.

getTransaction                      getSignaturesForAddress
getConfirmedTransaction             getConfirmedSignaturesForAddress2
getBlock                            getBlocks
getBlocksWithLimit                  getBlockSignatures
getFirstAvailableBlock

READ_HEAVY (25 credits, profile-gated)

These methods are supported by the codebase and are enabled on heavy-indexed endpoints. The Frankfurt hot-node launch endpoint returns -32004 without billing when this profile is disabled.

getProgramAccounts                  getLargestAccounts
simulateBundle

SEND (2 credits)

sendTransaction                     sendSmartTransaction

SEND_BUNDLE (10 credits)

sendBundle

sendBundle is credit-gated and costs more credits because it is resource-intensive.

DENIED

The following methods are not supported:

requestAirdrop

Error Responses

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

See Error Reference for all error codes.

POST /account/activate

Create or activate an account. Idempotent — calling with an already-registered pubkey returns the existing account.

This endpoint uses wallet signature auth (sig_only middleware). Only per-request wallet signature headers are accepted.

Request

POST /account/activate
Content-Type: application/json
X-Pubkey: <base58-pubkey>
X-Signature: <base58-signature>
X-Timestamp: <unix-timestamp>
X-Nonce: <hex-nonce>

{}

Response

{
  "ok": true,
  "pubkey": "YourPublicKeyBase58...",
  "api_key": "srpc_live_...",
  "deposit_address": "SharedDepositWalletATA...",
  "funding": {
    "asset": "USDC",
    "network": "solana",
    "deposit_address": "SharedDepositWalletATA...",
    "credits_per_usdc": 10000,
    "credit_expiry_seconds": 864000,
    "credit_expiry_days": 10,
    "attribution": "send USDC from the same wallet pubkey used to activate the account"
  },
  "credits_per_usdc": 10000,
  "credit_expiry_seconds": 864000,
  "balance": 0,
  "created": true
}

api_key is returned only when a new key is generated. Bots can ignore it and keep using per-request wallet signatures for all authenticated endpoints.

Errors

Status Description
401 Invalid signature or timestamp
500 Internal server error

GET /account/info

Get account details including credit balance and usage.

Request

GET /account/info
X-Pubkey: <base58-pubkey>
X-Signature: <base58-signature>
X-Timestamp: <unix-timestamp>
X-Nonce: <hex-nonce>

Or:

GET /account/info
Authorization: Bearer <token>

Response

{
  "ok": true,
  "pubkey": "YourPublicKeyBase58...",
  "balance": 84521,
  "deposit_address": "SharedDepositWalletATA...",
  "status": "active",
  "total_consumed_credits": 415479,
  "created_at": 1705312200,
  "last_deposit": {},
  "credit_batches": []
}

Errors

Status Description
401 Invalid authentication
404 Account not found

GET /account/ledger

Get credit transaction history (deposits, debits, adjustments).

Request

GET /account/ledger
Authorization: Bearer <token>

Response

{
  "entries": [
    {
      "type": "deposit",
      "amount": 10000,
      "balance": 10000,
      "description": "USDC deposit: 1.0 USDC",
      "timestamp": "2025-01-15T10:31:00Z"
    }
  ]
}

GET /account/history

Get usage history (RPC call log with credits consumed).

Request

GET /account/history
Authorization: Bearer <token>

Response

{
  "entries": [
    {
      "method": "getSlot",
      "credits": 1,
      "timestamp": "2025-01-15T10:32:00Z"
    }
  ]
}

POST /account/api-key

Generate a persistent API key for bearer token authentication. Regenerating invalidates the previous key.

Request

POST /account/api-key
Authorization: Bearer <token>

Or with wallet signature headers.

Response

{
  "ok": true,
  "api_key": "srpc_live_<base64url>",
  "message": "Save this key — it will not be shown again."
}

POST /account/confirm-deposit

Confirm a USDC deposit by providing the transaction signature. This can speed up credit assignment if the automatic detection hasn't processed the deposit yet.

Request

POST /account/confirm-deposit
Authorization: Bearer ***
Content-Type: application/json

{
  "signature": "5xYz...base58..."
}

Response

{
  "ok": true,
  "credits_added": 10000,
  "new_balance": 10000,
  "already_processed": false
}

POST /auth/challenge

Request a challenge for session token authentication.

Request

POST /auth/challenge
Content-Type: application/json

{
  "pubkey": "YourPublicKeyBase58..."
}

No authentication required for this endpoint.

Response

{
  "challenge": "a1b2c3d4e5f67890abcdef1234567890a1b2c3d4e5f67890abcdef1234567890",
  "expires_in": 300
}

The challenge is a 64-character hex string (32 random bytes). Valid for 300 seconds (5 minutes).

Errors

Status Description
400 Invalid pubkey format or account not found
429 Too many challenge requests

POST /auth/verify

Submit a signed challenge to receive a session token. Sign the raw challenge hex string bytes with your Ed25519 keypair.

Request

POST /auth/verify
Content-Type: application/json

{
  "pubkey": "YourPublicKeyBase58...",
  "challenge": "a1b2c3d4e5f67890abcdef1234567890a1b2c3d4e5f67890abcdef1234567890",
  "signature": "Base58EncodedSignature..."
}

The challenge must be the exact 64-character hex string from /auth/challenge.

Response

{
  "token": "64-char-hex-session-token...",
  "expires_in": 3600
}

Errors

Status Description
400 Missing or malformed fields
401 Invalid signature or expired challenge
404 Account not found

POST /auth/logout

Revoke the current session token.

Request

POST /auth/logout
Authorization: Bearer <token>

Response

{
  "status": "ok"
}

Jito Endpoints

POST /jito/sendBundle

Submit a Jito bundle for MEV-protected transaction submission.

Cost: 10 credits per call.

POST /jito/sendBundle
Authorization: Bearer <token>
Content-Type: application/json

{
  "transactions": ["base58tx1...", "base58tx2..."]
}

POST /jito/getBundleStatuses

Check the status of previously submitted bundles.

Cost: 2 credits per call.

POST /jito/getBundleStatuses
Authorization: Bearer <token>
Content-Type: application/json

{
  "bundleIds": ["bundleId1...", "bundleId2..."]
}

GET /jito/getTipAccounts

Get the list of Jito tip accounts.

Cost: 1 credit per call.

GET /jito/getTipAccounts
Authorization: Bearer <token>

GET /jito/tipFloor

Get the current Jito tip floor (minimum tip amount).

Cost: 1 credit per call.

GET /jito/tipFloor
Authorization: Bearer <token>

Bulk Endpoints

POST /bulk/getBalances

Batch balance lookups for multiple accounts in a single request.

POST /bulk/getBalances
Authorization: Bearer <token>
Content-Type: application/json

{
  "accounts": ["pubkey1...", "pubkey2...", "pubkey3..."]
}

POST /bulk/getTokenBalances

Batch token balance lookups for multiple accounts.

POST /bulk/getTokenBalances
Authorization: Bearer <token>
Content-Type: application/json

{
  "accounts": ["pubkey1...", "pubkey2..."],
  "mint": "TokenMintAddress..."
}

POST /bulk/getTransactions

Batch transaction lookups.

POST /bulk/getTransactions
Authorization: Bearer <token>
Content-Type: application/json

{
  "signatures": ["sig1...", "sig2...", "sig3..."]
}

Webhooks

POST /webhooks

Create a webhook subscription.

POST /webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["account_change"],
  "filter": {
    "accounts": ["pubkey1..."]
  }
}

GET /webhooks

List all webhook subscriptions for your account.

GET /webhooks
Authorization: Bearer <token>

DELETE /webhooks/{id}

Delete a webhook subscription.

DELETE /webhooks/abc123
Authorization: Bearer <token>

GET /ws

WebSocket endpoint for streaming subscriptions.

Connection

wss://rpc.nodius.xyz/ws

Authentication via the Authorization header:

Authorization: Bearer <token>

Or via the Sec-WebSocket-Protocol header (for clients that don't support custom headers):

Sec-WebSocket-Protocol: auth.<token>

Subscription Messages

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "accountSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {"encoding": "base64", "commitment": "confirmed"}
  ]
}

Supported Subscription Methods

Method Unsubscribe Description
accountSubscribe accountUnsubscribe Account data changes
logsSubscribe logsUnsubscribe Transaction logs
programSubscribe programUnsubscribe Program account changes
signatureSubscribe signatureUnsubscribe Transaction signature status
slotSubscribe slotUnsubscribe Slot updates
rootSubscribe rootUnsubscribe Root slot updates
blockSubscribe blockUnsubscribe Block updates

See the WebSocket Guide for detailed usage.

Yellowstone gRPC

High-performance streaming via Yellowstone geyser plugin.

Endpoint

grpc://rpc.nodius.xyz:10001

Authentication

Provide your session token or API key via the gRPC metadata x-token field:

x-token: <session-token-or-api-key>

Billing

60 credits per minute per active connection. Credits are deducted continuously while connected.

Capabilities

See the Yellowstone gRPC documentation for the proto definitions and client libraries.

GET /health

Public health check endpoint. No authentication required.

Request

GET /health

Response

{
  "status": "ok",
  "solanaSlot": 285943216,
  "solanaBlockHeight": 265234567,
  "nodeVersion": "2.0.15",
  "uptime": 864000
}
Status HTTP Code Description
ok 200 Healthy
degraded 200 Operational but experiencing issues
unhealthy 503 Not operational

Metrics

Prometheus-compatible metrics are available at /internal/metrics on the admin-only localhost port (9090). This endpoint is not publicly accessible.

If you need to monitor your own usage, use the X-Credits-Remaining response header or the GET /account/info endpoint.

Response Headers

All authenticated endpoints include these headers:

Header Description
X-Credits-Remaining Current credit balance
X-Credits-Low true if balance < 1,000 credits
X-Request-Id Unique request identifier for debugging
X-Ratelimit-Limit Requests per second limit
X-Ratelimit-Remaining Remaining requests in current window
X-Ratelimit-Reset Unix timestamp when rate limit resets

Content Types

Nodius — nodius.xyz · Telegram · Status