Public RPC Docs

Integrate our RPC without reading the repo first.

These are the public-facing transport docs for teams that want to consume the shared gateway or point their own nodes and provider endpoints at the same project-scoped edge.

Back to status OpenAPI data plane OpenAPI control plane

Live base URL

RPC gatewayhttps://rpc.swivy.dev

HTTP path shapehttps://rpc.swivy.dev/{network}/v3/{projectId}

WebSocket path shapewss://rpc.swivy.dev/{network}/v3/{projectId}

Overview

What teams actually integrate with

Use our shared gateway: issue project credentials and send raw JSON-RPC to project-scoped URLs.

Bring your own upstreams: register your node or provider endpoint, then pin project traffic to that upstream pool with networkUpstreams .

Shared RPC

Best for fast integration. We manage the public gateway path, auth, limits, and upstream routing shape.

Dedicated project routing

Best for enterprise isolation. A project can be pinned to a dedicated upstream set without changing the client-facing URL shape.

Auth

Project secret auth

x-project-secret: <PROJECT_SECRET>
x-api-key: <PROJECT_SECRET>
Authorization: Bearer <PROJECT_SECRET>
Basic auth with project ID as username and secret as password
?projectSecret=<PROJECT_SECRET> for websocket auth

Recommended default: bearer auth for HTTP and query auth for websocket clients that cannot set custom headers reliably.

Transport

Raw JSON-RPC pass-through

EVM and Solana HTTPhttps://rpc.swivy.dev/{network}/v3/{projectId}

WebSocket RPCwss://rpc.swivy.dev/{network}/v3/{projectId}

This is a raw RPC transport layer. There is no separate broker API required for standard chain calls.

Discovery

Machine-readable contracts and live provider discovery

GET /api/provider/v1/metadata
GET /api/provider/v1/status
GET /api/provider/v1/projects/:projectId/descriptor
GET /api/provider/v1/projects/:projectId/swivy-config
GET /api/provider/v1/projects/:projectId/swivy-handoff

Data-plane OpenAPI Control-plane OpenAPI Swivy handoff contract

Examples

CLI and curl examples

Inspect provider metadatabash

curl "https://rpc.swivy.dev/api/provider/v1/metadata"

Inspect project transport descriptorbash

curl "https://rpc.swivy.dev/api/provider/v1/projects/<PROJECT_ID>/descriptor" \
  -H "authorization: Bearer <PROJECT_SECRET>"

Send an EVM JSON-RPC requestbash

curl -X POST "https://rpc.swivy.dev/eth-mainnet/v3/<PROJECT_ID>" \
  -H "content-type: application/json" \
  -H "authorization: Bearer <PROJECT_SECRET>" \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Send a Solana JSON-RPC requestbash

curl -X POST "https://rpc.swivy.dev/solana-mainnet/v3/<PROJECT_ID>" \
  -H "content-type: application/json" \
  -H "authorization: Bearer <PROJECT_SECRET>" \
  --data '{"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash","params":[]}'

Use websocket RPCtext

wss://rpc.swivy.dev/eth-mainnet/v3/<PROJECT_ID>?projectSecret=<PROJECT_SECRET>

Bring Your Own

Point your own nodes or provider endpoints

Log into the control plane and keep the session cookie.
Probe the upstream candidate before saving it.
Register the upstream once the probe passes.
Pin project traffic to your upstream IDs with networkUpstreams.

curl -c rpc-fabric.cookies -X POST "https://rpc.swivy.dev/auth/login" \
  -H "content-type: application/json" \
  --data '{
    "email": "ops@example.com",
    "password": "REPLACE_WITH_REAL_PASSWORD"
  }'

Probe an existing EVM node or provider endpointbash

curl -b rpc-fabric.cookies -X POST "https://rpc.swivy.dev/api/control-plane/upstreams/probe" \
  -H "content-type: application/json" \
  --data '{
    "networkKey": "eth-mainnet",
    "httpUrl": "https://your-eth-endpoint.example",
    "wsUrl": "wss://your-eth-endpoint.example",
    "httpHeaders": {
      "authorization": "Bearer YOUR_TOKEN"
    },
    "wsHeaders": {
      "authorization": "Bearer YOUR_TOKEN"
    }
  }'

curl -b rpc-fabric.cookies -X POST "https://rpc.swivy.dev/api/control-plane/upstreams" \
  -H "content-type: application/json" \
  --data '{
    "id": "company-eth-mainnet-a",
    "networkKey": "eth-mainnet",
    "httpUrl": "https://your-eth-endpoint.example",
    "wsUrl": "wss://your-eth-endpoint.example",
    "httpHeaders": {
      "authorization": "Bearer YOUR_TOKEN"
    },
    "wsHeaders": {
      "authorization": "Bearer YOUR_TOKEN"
    },
    "capabilities": ["standard", "write", "websocket"],
    "weight": 1
  }'

Pin a project to your own upstream poolbash

curl -b rpc-fabric.cookies -X PUT "https://rpc.swivy.dev/api/control-plane/projects/<PROJECT_ID>" \
  -H "content-type: application/json" \
  --data '{
    "networkUpstreams": {
      "eth-mainnet": ["company-eth-mainnet-a"],
      "solana-mainnet": ["company-solana-mainnet-a"]
    }
  }'

Generate a ready-to-share project handoff bundle from CLIbash

npm run rpc-infra:project -- create \
  --base-url https://rpc.swivy.dev \
  --admin-token <RPC_FABRIC_ADMIN_TOKEN> \
  --name company-production \
  --networks eth-mainnet,base-mainnet,arbitrum-one,optimism-mainnet,polygon-mainnet,solana-mainnet,solana-devnet \
  --project-secret-ref COMPANY_RPC_PROJECT_SECRET \
  --auth-scheme bearer \
  --solana-commitment confirmed \
  --format env

Networks

Live supported network matrix

The live network matrix is currently unavailable. When the provider metadata endpoint is reachable, this page lists the active network catalog automatically.

Limits and health

Rate limits, websocket caps, and status polling

Per-project limits come from the project descriptor endpoint.
HTTP responses expose RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy.
Retry-After is returned on 429.
/healthz is process liveness.
/readyz is gateway readiness.
/api/provider/v1/status is the provider-facing health document.
/metrics exposes Prometheus metrics.

Errors

What error shapes to expect

400 INVALID_JSON_RPC_BODY
400 BATCH_LIMIT_EXCEEDED
401 UNAUTHORIZED
401 PROJECT_NOT_FOUND
401 INVALID_SECRET
403 NETWORK_NOT_ALLOWED
403 METHOD_NOT_ALLOWED
404 NETWORK_NOT_FOUND
429 RATE_LIMITED
503 LIMITER_UNAVAILABLE

When no upstream can serve the request, the data plane returns HTTP 502 with a JSON-RPC error envelope.