Endpoints

Authentication

Every request needs X-Api-Key, X-Timestamp, and X-Signature (HMAC-SHA256), same scheme as Account and Address Watch.

Sign the path starting with /v1/… (for example /v1/endpoints or /v1/endpoints/12/status). Query string is not part of the signature. For POST/PATCH, sign the raw JSON body bytes you send.

Errors

Failures use ok: false and a string error. Typical HTTP status: 401 (auth/signature), 403 (API key IP allowlist), 400 (validation / business error, e.g. plan limit), 500 (server).

Error example

{
  "ok": false,
  "error": "Invalid signature."
}

GET /v1/endpoints

List all JSON-RPC endpoints owned by the billing workspace.

Response fields

• Sign path /v1/endpoints with an empty body.

Response example

{
  "ok": true,
  "endpoints": [
    {
      "id": 12,
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Prod Ethereum",
      "status": "active",
      "network_id": 1,
      "network_name": "Ethereum",
      "network_slug": "ethereum",
      "network_environment_id": 2,
      "env_slug": "mainnet",
      "url": "https://ethereum-mainnet.rpcnode.dev/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rps_limit": 50,
      "plan_id": 2,
      "created_at": "2026-08-01T12:00:00+00:00",
      "version": "v1.14.0",
      "block_height": 21000000,
      "allowed_ips": []
    }
  ]
}

GET /v1/endpoints/available-networks

Networks and environment slugs you can use when creating an endpoint (filtered by plan).

Response fields

• Sign path /v1/endpoints/available-networks with an empty body.

Response example

{
  "ok": true,
  "networks": [
    {
      "id": 1,
      "uuid": "…",
      "name": "Ethereum",
      "slug": "ethereum",
      "sort": 10,
      "environment_kinds": ["mainnet", "sepolia"]
    }
  ],
  "network_limit": null,
  "allowed_network_slugs": []
}

POST /v1/endpoints

Create a JSON-RPC endpoint. Provide network_environment_id, or network_id + env_slug, plus name. Counts against plan.endpoints_limit.

Request body

Response fields

• Sign path /v1/endpoints with the raw JSON body.
• Provide either network_environment_id, or both network_id and env_slug (typical path after available-networks).
• Example body: {"name":"Prod Ethereum","network_id":1,"env_slug":"mainnet"}
• Alternative: {"name":"Prod Ethereum","network_environment_id":2}

Response example

{
  "ok": true,
  "endpoint": {
  "id": 12,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Prod Ethereum",
  "status": "active",
  "network_id": 1,
  "network_name": "Ethereum",
  "network_slug": "ethereum",
  "network_environment_id": 2,
  "env_slug": "mainnet",
  "url": "https://ethereum-mainnet.rpcnode.dev/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "rps_limit": 50,
  "plan_id": 2,
  "created_at": "2026-08-01T12:00:00+00:00",
  "version": "v1.14.0",
  "block_height": 21000000,
  "allowed_ips": []
}
}

GET /v1/endpoints/usage

Aggregate credit/request usage across all endpoints for the last N calendar days (plus top RPC methods).

Query parameters

Response fields

• Query string is not part of the signature — sign path /v1/endpoints/usage with an empty body.
• series is oldest → newest, one point per day (zeros when no usage).
• methods are per-RPC-method totals for the same window (highest requests first).

Response example

{
  "ok": true,
  "usage": {
    "days": 30,
    "total_requests": 5400,
    "total_credits": 12000,
    "series": [
      { "date": "2026-07-08", "requests": 10, "credits": 20 },
      { "date": "2026-08-06", "requests": 100, "credits": 250 }
    ],
    "methods": [
      { "method": "eth_call", "requests": 2000, "credits": 4000 }
    ]
  }
}

GET /v1/endpoints/{id}/usage

Credit/request usage for one endpoint (same shape as workspace usage).

Query parameters

Response fields

• Sign path /v1/endpoints/{id}/usage — query string is not part of the signature.
• {id} is the numeric endpoint.id from list/create (not the UUID).

Response example

{
  "ok": true,
  "usage": {
    "days": 7,
    "total_requests": 100,
    "total_credits": 250,
    "series": [
      { "date": "2026-07-31", "requests": 0, "credits": 0 },
      { "date": "2026-08-06", "requests": 100, "credits": 250 }
    ],
    "methods": [
      { "method": "eth_getBalance", "requests": 50, "credits": 50 }
    ]
  }
}

PATCH /v1/endpoints/{id}/status

Set endpoint status to active or paused (pauses JSON-RPC traffic at the gateway).

Request body

Response fields

• Sign path /v1/endpoints/{id}/status with the raw JSON body.
• Example body: {"status":"paused"}
• There is no DELETE — use paused to stop traffic (parity with connect).

Response example

{
  "ok": true,
  "endpoint": {
  "id": 12,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Prod Ethereum",
  "status": "paused",
  "network_id": 1,
  "network_name": "Ethereum",
  "network_slug": "ethereum",
  "network_environment_id": 2,
  "env_slug": "mainnet",
  "url": "https://ethereum-mainnet.rpcnode.dev/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "rps_limit": 50,
  "plan_id": 2,
  "created_at": "2026-08-01T12:00:00+00:00",
  "version": "v1.14.0",
  "block_height": 21000000,
  "allowed_ips": []
}
}

PATCH /v1/endpoints/{id}/allowed-ips

Replace the client IP allowlist for the gateway. Empty array clears the restriction (allow all).

Request body

Response fields

• Sign path /v1/endpoints/{id}/allowed-ips with the raw JSON body.
• Example body: {"allowed_ips":["203.0.113.10","2001:db8::1"]}
• Clear restriction: {"allowed_ips":[]}

Response example

{
  "ok": true,
  "endpoint": {
  "id": 12,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Prod Ethereum",
  "status": "active",
  "network_id": 1,
  "network_name": "Ethereum",
  "network_slug": "ethereum",
  "network_environment_id": 2,
  "env_slug": "mainnet",
  "url": "https://ethereum-mainnet.rpcnode.dev/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "rps_limit": 50,
  "plan_id": 2,
  "created_at": "2026-08-01T12:00:00+00:00",
  "version": "v1.14.0",
  "block_height": 21000000,
  "allowed_ips": ["203.0.113.10"]
}
}

Tips

• Sign every request with X-Api-Key, X-Timestamp, and X-Signature (see Authentication).
• JSON-RPC calls go to endpoint.url — do not send Public API HMAC headers on those URLs.
• There is no DELETE — use PATCH …/status with paused to stop traffic.
• Plan caps: endpoints_limit (count) and rps_limit (per endpoint); see Account.
• Address Watch and Account routes are documented on their own pages.

Related

• Public API
• Public API overview
• Authentication & signing
• Account
• Address Watch
• Getting started (JSON-RPC)