Docs

Start from wallet auth to first request in minutes.

This guide covers the full self-serve path on Fyxvo devnet. Wallet auth, project activation, SOL funding, relay usage, analytics, and SDK reference — all in one place.

Devnet only

Fyxvo is live on Solana devnet today. SOL is the active funding path. USDC remains intentionally configuration-gated until it is explicitly enabled for a deployment.

Need a direct line while integrating?

For launch-fit questions, issue reports, or managed rollout conversations, use the community paths below or the contact page.

X Discord Telegram

Section 1

Introduction

What Fyxvo is, who it is for, and what is live on devnet today.

What is Fyxvo

A developer platform for Solana teams that need a real, funded RPC relay path — not a mock dashboard.

Fyxvo provides wallet-authenticated project management, on-chain SOL funding, a standard relay, a separate priority relay path, per-project analytics, and a public status surface. Everything connects from wallet identity to observable traffic in a single controlled flow.

Who it is for

Solana teams validating funded RPC, priority relay, and analytics before widening traffic.

Use Fyxvo if you want to confirm wallet-authenticated project control, SOL-funded gateway access, priority routing behavior, request analytics, and a managed launch path without building your own infrastructure first.

What is live today

The full devnet path is active: wallet auth, project activation, SOL funding, standard relay, priority relay, analytics, and public status.

USDC remains gated and the current operator topology is managed infrastructure — not an open external operator marketplace. Both limits are stated explicitly throughout the product and in these docs.

Section 2

Quickstart

The four-step path from wallet connect to first confirmed relay request.

Step 1

Connect a wallet

Open the dashboard. The app requests a challenge from the API, asks the connected wallet to sign it, and exchanges that signature for a JWT-backed API session. Phantom is the most direct path for browser-first devnet usage.

Step 2

Create and activate a project

Project creation prepares the on-chain activation transaction immediately. The project becomes usable as soon as the wallet signs and devnet confirms it. The API derives the PDA and prepares everything — you only need to sign.

Step 3

Fund with SOL

Prepare a SOL funding transaction from the project page, review the lamport amount, sign it in the wallet, and wait for API verification. The API then refreshes the project's on-chain balance view so the gateway can accept traffic.

Step 4

Issue a key and send traffic

Generate a relay key scoped to rpc:request. Copy the /rpc endpoint and send a small JSON-RPC request. That first request should appear in project analytics and on the status surface within seconds.

Complete working example

Five Minute Quickstart

From zero to a live devnet relay request using curl only. No SDK required.

Step 1 — Request an auth challenge

curl -s -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET_ADDRESS_BASE58"}'

# Save the nonce and message from the response
# { "walletAddress": "...", "nonce": "abc123", "message": "Fyxvo Authentication\nWallet: ...\nNonce: abc123\n..." }

Step 2 — Sign the message with your wallet CLI (e.g. solana-keygen)

# Sign the exact message string returned from the challenge endpoint.
# Using the Solana CLI (base58 output):
echo -n "Fyxvo Authentication\nWallet: YOUR_WALLET\nNonce: abc123\n..." | \
  solana sign-offchain-message - --keypair ~/.config/solana/id.json

# Or use @solana/wallet-adapter-base in the browser:
# const sig = await wallet.signMessage(Buffer.from(message));
# const sigBase58 = bs58.encode(sig);

Step 3 — Verify and get your JWT

curl -s -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "walletAddress": "YOUR_WALLET_ADDRESS_BASE58",
    "message": "THE_EXACT_CHALLENGE_MESSAGE",
    "signature": "YOUR_BASE58_SIGNATURE"
  }'

# { "token": "eyJhbGci...", "user": { "walletAddress": "...", "role": "MEMBER" } }
export JWT="eyJhbGci..."

Step 4 — Issue an API key (after creating and funding a project in the dashboard)

curl -s -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/api-keys \
  -H "authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -d '{"label":"my-key","scopes":["project:read","rpc:request"]}'

# { "item": { "id": "...", "prefix": "fyxvo_live_...", ... }, "plainTextKey": "fyxvo_live_...secret" }
export API_KEY="fyxvo_live_...secret"

Step 5 — Send your first relay request

curl -s -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# { "jsonrpc": "2.0", "result": "ok", "id": 1 }

# Priority relay (requires priority:relay scope):
curl -s -X POST https://rpc.fyxvo.com/priority \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

That's it

Your first request is now in the relay logs. Check the Analytics page to see it appear within seconds. Fund more SOL to increase capacity — 1,000 lamports per standard request, 3,000 per compute-heavy, 5,000 per priority.

Quickstarts

Framework Quickstarts

Ready-to-run examples for the most common Solana development environments.

Server component example using @solana/web3.js in a Next.js App Router route handler.

app/api/solana/route.ts

// app/api/solana/route.ts
import { Connection } from "@solana/web3.js";

const connection = new Connection(
  `https://rpc.fyxvo.com/rpc?api-key=${process.env.FYXVO_API_KEY}`
);

export async function GET() {
  const slot = await connection.getSlot();
  return Response.json({ slot });
}

Section 3

Authentication

Wallet-signed JWT flow: challenge, sign, verify.

How the wallet session works

The API issues a short-lived challenge string. The wallet signs it off-chain. The signed payload is exchanged for a JWT. That JWT becomes the bearer token for all authenticated API actions: project management, funding, analytics, and key management.

Step 1 — Request a challenge

curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

Step 2 — Sign in the browser

Use wallet.signMessage(Buffer.from(challenge)) from @solana/wallet-adapter-base. Convert the resulting Uint8Array signature to base58 before sending.

Full auth flow

# 1. Get challenge — returns the exact message to sign
curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

# Response: { "walletAddress": "...", "nonce": "...", "message": "fyxvo:YOUR_WALLET:NONCE" }

# 2. Sign the message with your wallet (browser, @solana/wallet-adapter-base)
const encoded = new TextEncoder().encode(message);
const signatureBytes = await wallet.signMessage(encoded);
const signature = bs58.encode(signatureBytes);

# 3. Verify signature and receive JWT
curl -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "walletAddress": "YOUR_WALLET",
    "message": "<message-from-step-1>",
    "signature": "<base58-signature>"
  }'

# Response: { "token": "eyJ...", "user": { "id": "...", "walletAddress": "...", "role": "MEMBER" } }

JWT expiry

Tokens expire after 24 hours. Re-authenticate by repeating the challenge + verify flow. There is no refresh token endpoint; the wallet signs a new challenge each time.

Supported wallets

Phantom, Solflare, Backpack, and any Wallet Standard compatible wallet work through the Solana wallet adapter layer. Phantom is the fastest for browser-first devnet usage.

Section 4

Funding

SOL funding flow on devnet — prepare, sign, verify.

SOL is live on devnet

The full SOL funding path is active. Fund your devnet wallet first (via the Solana faucet), then fund the project through Fyxvo. That keeps the control plane, Anchor program, and gateway aligned before you scale request volume.

Prepare, sign, and verify a funding transaction

# 1. Prepare the unsigned funding transaction
curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/funding/prepare \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"asset":"SOL","amountLamports":100000000,"funderWalletAddress":"YOUR_WALLET"}'

# Response: { "item": { "id": "FUNDING_ID", "transactionBase64": "<unsigned-tx>", "amount": "100000000" } }

# 2. Decode, sign, and broadcast (using @solana/web3.js)
import { Transaction, Connection } from "@solana/web3.js";

const fundingItem = response.item;
const tx = Transaction.from(Buffer.from(fundingItem.transactionBase64, "base64"));
const signed = await wallet.signTransaction(tx);
const connection = new Connection("https://api.devnet.solana.com");
const sig = await connection.sendRawTransaction(signed.serialize());
await connection.confirmTransaction(sig, "confirmed");

# 3. Verify the confirmed transaction with the API
curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/funding/FUNDING_ID/verify \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"signature": "<tx-signature>"}'

Unsigned transaction review

The API returns the unsigned transaction encoded in base64. Decode and inspect it before signing. This keeps the funding flow explicit and auditable.

USDC stays gated

USDC funding exists in the protocol but is configuration-gated. It will not accept USDC transfers until the deployment explicitly enables it via runtime config.

Section 5

Standard RPC

Send standard JSON-RPC traffic through the /rpc relay endpoint.

Required scope

Keys used on the standard path must carry the rpc:request scope. Under-scoped keys receive a 403, not silent broad access.

Standard relay request

# Standard relay — requires rpc:request scope
curl -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

# Also accepts Authorization: Bearer
curl -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash","params":[{"commitment":"confirmed"}]}'

What the gateway does

Validates the API key and checks its scope
Checks the project's funded SOL balance against the request cost
Routes to the upstream Solana RPC node pool with fallback
Logs the request, latency, and result for analytics rollups
Deducts the lamport cost from the project balance

Endpoint

Standard path: https://rpc.fyxvo.com/rpc

Section 6

Priority Relay

Latency-sensitive traffic on the /priority endpoint with a separately scoped key.

Required scope

Priority keys must carry both rpc:request and priority:relay scopes. Sending a standard key to /priority returns 403.

Priority relay request

# Priority relay — requires rpc:request AND priority:relay scopes
curl -X POST https://rpc.fyxvo.com/priority \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["<base64-tx>",{"encoding":"base64","skipPreflight":false}]}'

Standard vs priority

Property	Standard	Priority
Endpoint	/rpc	/priority
Scope	rpc:request	+ priority:relay
Rate limit	300 / min	60 / min

Why they are separate

Keeping standard and priority traffic on separate paths gives teams clearer pricing, independent rate windows, and better operational discipline. A single key cannot accidentally consume the priority budget.

Section 7

Analytics

Monitor request volume, latency, and errors across your Fyxvo projects.

Fyxvo provides a two-level analytics surface: an overview endpoint that aggregates totals across all your projects, and a per-project endpoint that surfaces method breakdowns, latency percentiles, status code distributions, and recent error events. Both endpoints require a valid JWT and respect the standard rate limit window.

Section 7

Analytics API

Fetch usage data across all projects or drill into a specific project.

GET https://api.fyxvo.com/v1/analytics/overview

curl https://api.fyxvo.com/v1/analytics/overview \
  -H "authorization: Bearer YOUR_JWT"

# Response shape:
# {
#   "item": {
#     "totals": { "projects": 3, "apiKeys": 5, "fundingRequests": 2, "requestLogs": 14200 },
#     "latency": { "averageMs": 42, "maxMs": 312 },
#     "requestsByService": [{ "service": "gateway", "count": 14200 }]
#   }
# }

GET https://api.fyxvo.com/v1/analytics/projects/:id

curl https://api.fyxvo.com/v1/analytics/projects/YOUR_PROJECT_ID?range=24h \
  -H "authorization: Bearer YOUR_JWT"

# Range options: 1h | 6h | 24h | 7d | 30d (default: all time)
# Response shape:
# {
#   "item": {
#     "totals": { "requestLogs": 4800, "apiKeys": 2, "fundingRequests": 1 },
#     "latency": { "averageMs": 38, "maxMs": 210, "p95Ms": 95 },
#     "statusCodes": [{ "statusCode": 200, "count": 4750 }, { "statusCode": 429, "count": 50 }],
#     "recentRequests": [{ "route": "/rpc", "method": "POST", "statusCode": 200, "durationMs": 38 }]
#   }
# }

Overview endpoint

Aggregates totals across all projects owned by the authenticated wallet: total requests, success rate, average latency, and 24-hour rolling count.

Project endpoint

Returns per-project metrics including method breakdown, recent error log, and latency percentiles for both standard and priority paths.

Auth required

Both endpoints require a valid JWT Bearer token in the Authorization header. Use the wallet auth flow to obtain one.

Project API

Public Stats API

Read project-level public stats with a project-scoped API key from your backend services.

Keep keys off the client

Pass x-api-key from a backend service, serverless function, or CI job. Do not ship project keys in browser bundles.

curl

curl https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public \
  -H "x-api-key: $FYXVO_API_KEY"

JavaScript fetch (server-side)

const response = await fetch("https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public", {
  headers: {
    "x-api-key": process.env.FYXVO_API_KEY!,
  },
  cache: "no-store",
});

const stats = await response.json();
console.log(stats);

Node.js

import process from "node:process";

const response = await fetch("https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public", {
  headers: {
    "x-api-key": process.env.FYXVO_API_KEY ?? "",
  },
});

console.log(await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public",
    headers={"x-api-key": os.environ["FYXVO_API_KEY"]},
    timeout=10,
)

print(response.json())

Interactive

API Explorer

Try live API endpoints directly from the docs. Paste your JWT token to test authenticated routes.

API Explorer

GET/health

Check API service health and database connectivity.

curl

curl https://api.fyxvo.com/health \
  -H "Content-Type: application/json"

Platform

Webhooks

Receive HTTP POST callbacks when events happen in your project.

Webhooks let you integrate Fyxvo events into your own systems. Every delivery includes an x-fyxvo-signature header with format sha256=<hex>.

Supported events

funding.confirmedapikey.createdapikey.revokedbalance.lowproject.activated

Create a webhook

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/webhooks \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"url":"https://your-server.example.com/webhook","events":["funding.confirmed","balance.low"]}'

Test a webhook

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/webhooks/WEBHOOK_ID/test \
  -H "authorization: Bearer YOUR_JWT"

Signature verification (Node.js)

const crypto = require('crypto');
const sig = req.headers['x-fyxvo-signature'];
const computed = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (sig !== computed) return res.status(401).send('Unauthorized');

Retry behavior

If your endpoint is unreachable, Fyxvo retries once after 30 seconds. After two failures the webhook remains active but lastTriggeredAt is not updated. URLs must be HTTPS — localhost and private IP ranges are blocked.

Platform

Team Collaboration

Invite team members to your project by Solana wallet address.

Project owners can invite other Fyxvo users by wallet address. Invitations are pending until the invitee accepts via PATCH /v1/projects/:id/members/:memberId/accept.

Member permissions

Members can view analytics and API keys but cannot delete the project or change ownership. Only the project owner can invite or remove members.

Team management

Team management is in Settings → Team on the project page. Pending invitations are shown until accepted or removed.

Invite a member

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/members/invite \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"walletAddress":"MEMBER_WALLET_ADDRESS"}'

List members

curl https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/members \
  -H "authorization: Bearer YOUR_JWT"

Platform

Public Project Pages

Share your project's aggregate stats publicly — no API key required.

Enable a public URL for your project from Settings → Project settings → Public profile. The public page at /p/[your-slug] shows total requests and average latency. No API keys or balances are shown.

README badge

Add a live status badge to your GitHub README. The badge shows latency and updates every 5 minutes via CDN cache.

README badge markdown

[![Fyxvo Status](https://api.fyxvo.com/badge/project/YOUR_SLUG)](https://www.fyxvo.com/p/YOUR_SLUG)

Playground

The API Playground lets you send live JSON-RPC requests to the Fyxvo gateway and inspect responses without writing any code.

Compare Mode

Toggle Compare in the request builder to run the same request on both the standard and priority paths simultaneously. The priority response badge turns green when it is faster.

Schema Panel

Click Schema next to any method to see the expected response shape — field names, types, and descriptions — before you send the request.

Shareable URLs

Click Share to encode the current method and parameters into the URL. Send the link to a colleague and they will land on the same request configuration.

Section 8

SDK Reference

@fyxvo/sdk — TypeScript SDK for the Fyxvo gateway and control-plane API.

SDK install

Install @fyxvo/sdk with npm, yarn, or pnpm. The package exposes a typed client for the gateway and API. Use the curl / fetch examples in the Standard RPC and Priority Relay sections if you prefer to integrate without the SDK.

npm

npm install @fyxvo/sdk

yarn

yarn add @fyxvo/sdk

pnpm

pnpm add @fyxvo/sdk

Create a client

import { createFyxvoClient } from "@fyxvo/sdk";

const client = createFyxvoClient({
  baseUrl: "https://rpc.fyxvo.com",
  apiKey: process.env.FYXVO_API_KEY,
});

client.rpc() — standard relay

// Standard RPC request
const health = await client.rpc({
  id: 1,
  method: "getHealth",
});

// With params
const blockhash = await client.rpc({
  id: 2,
  method: "getLatestBlockhash",
  params: [{ commitment: "confirmed" }],
});

console.log(blockhash.result.value.blockhash);

client.rpc() with /priority path — priority relay

// Priority relay request (requires priority:relay scoped key)
// Pass the /priority path via the options second argument
const slot = await client.rpc(
  { id: 1, method: "getSlot" },
  { path: "/priority" }
);

if ("result" in slot) {
  const slotNumber = slot.result as number;
  // use slotNumber
}

Error handling

import { FyxvoError, FyxvoApiError } from "@fyxvo/sdk";

try {
  const result = await client.rpc({ id: 1, method: "getHealth" });
} catch (err) {
  if (err instanceof FyxvoApiError) {
    // HTTP-level error from the gateway (4xx / 5xx)
    // err.status holds the HTTP status code, err.message has the description
    const status: number | undefined = err.status;
    const message: string = err.message;
    void status; void message;
  } else if (err instanceof FyxvoError) {
    // SDK-level error (network, timeout, config)
    const message: string = err.message;
    void message;
  }
}

TypeScript — full wallet auth flow

import { createFyxvoClient } from "@fyxvo/sdk";

// Step 1 — request a challenge
const api = createFyxvoClient({ baseUrl: "https://api.fyxvo.com" });
const challenge = await api.request<{ message: string; nonce: string }>({
  method: "POST",
  path: "/v1/auth/challenge",
  body: { walletAddress: "YOUR_WALLET_ADDRESS" },
});

// Step 2 — sign the message with your wallet
const encoded = new TextEncoder().encode(challenge.message);
const sigBytes = await wallet.signMessage(encoded);
const signature = bs58.encode(sigBytes);

// Step 3 — verify and receive a JWT
const session = await api.request<{ token: string }>({
  method: "POST",
  path: "/v1/auth/verify",
  body: {
    walletAddress: "YOUR_WALLET_ADDRESS",
    message: challenge.message,
    signature,
  },
});

// Step 4 — use the JWT as a bearer token for subsequent calls
const authedClient = createFyxvoClient({
  baseUrl: "https://api.fyxvo.com",
  headers: { authorization: `Bearer ${session.token}` },
});

TypeScript — create an API key

// Create a gateway relay API key (requires JWT from auth flow)
const authedClient = createFyxvoClient({
  baseUrl: "https://api.fyxvo.com",
  headers: { authorization: "Bearer YOUR_JWT" },
});

const created = await authedClient.request<{
  item: { id: string; prefix: string; scopes: string[] };
  plainTextKey: string;
}>({
  method: "POST",
  path: "/v1/api-keys",
  body: { label: "my-relay-key", scopes: ["rpc:request"] },
});

const apiKey = created.plainTextKey;

TypeScript — typed gateway RPC call

import { createFyxvoClient, type RpcResponse } from "@fyxvo/sdk";

// Gateway client — use your relay API key here
const gateway = createFyxvoClient({
  baseUrl: "https://rpc.fyxvo.com",
  apiKey: process.env.FYXVO_API_KEY,
});

// Standard RPC call
const health = await gateway.rpc<string>({ method: "getHealth" });

// With typed params
interface BlockhashResult {
  blockhash: string;
  lastValidBlockHeight: number;
}
const response: RpcResponse<{ value: BlockhashResult }> = await gateway.rpc({
  id: 1,
  method: "getLatestBlockhash",
  params: [{ commitment: "confirmed" }],
});

if ("result" in response) {
  const blockhash: string = response.result.value.blockhash;
  void blockhash;
}

Python (requests) — gateway RPC call

import requests

response = requests.post(
    "https://rpc.fyxvo.com/rpc",
    headers={"x-api-key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "getHealth", "params": []}
)
print(response.json())

FyxvoError

Base class for all SDK errors. Covers network failures, timeouts, and configuration issues. Always catch this as a fallback.

FyxvoApiError

Extends FyxvoError with an HTTP statusCode. Thrown when the gateway or API returns a 4xx or 5xx response. Check statusCode === 429 for rate limit handling.

Section 9

Rate Limits

Per-key limits for standard and priority paths, and how to handle 429 responses.

Standard path

Limit: 300 requests per 60-second window

Scope: rpc:request

Enforcement: Redis-backed, per API key

Priority path

Limit: 60 requests per 60-second window

Scope: priority:relay

Enforcement: Separate window from standard

429 handling with exponential backoff

# The gateway returns 429 when a key exceeds its rate window.
# Response headers include:
#   x-ratelimit-limit:     <requests per window>
#   x-ratelimit-remaining: <remaining in current window>
#   x-ratelimit-reset:     <unix timestamp when the window resets>

# Standard path (rpc:request scope) — 300 req / 60 s per key
# Priority path (priority:relay scope) — 60 req / 60 s per key

# Retry with backoff after a 429:
async function withRetry(fn, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err?.statusCode === 429 && attempt < maxAttempts - 1) {
        await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
      } else {
        throw err;
      }
    }
  }
}

Rate limit headers

Every response includes x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. Use these to implement adaptive backoff without waiting for a 429.

Gateway

Simulation Mode

Test against the gateway without using your project balance or touching Solana devnet.

What simulation mode does

Requests are free — no lamports are deducted.
Traffic is not forwarded to Solana devnet.
The gateway returns canned, deterministic responses.
Useful for SDK integration tests and CI pipelines.

Supported methods

getHealth
getSlot
getBalance
getLatestBlockhash

Other methods may pass through or return a stub error in simulation mode.

Enable simulation mode — append ?simulate=true

# Standard path with simulation enabled
curl -X POST "https://rpc.fyxvo.com/rpc?simulate=true" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

# Response (canned — not from devnet):
# {"jsonrpc":"2.0","id":1,"result":"ok"}

Production integrations

Simulation mode is intended for development and testing only. Production integrations must omit the ?simulate=true parameter to ensure requests are routed to Solana devnet and fees are applied correctly against your project balance.

Reference

API Versioning

How Fyxvo versions its REST API and what counts as a breaking change.

Current version

Version: v1

Base path: /v1/

Version header: X-Fyxvo-API-Version: v1

Version detection

Every API response includes the X-Fyxvo-API-Version: v1 header. Check this header in your client to detect version mismatches before they cause silent behavior changes.

Breaking changes

Changes to existing response field shapes or types
Removal of response fields
Changes to the authentication mechanism
Changes to required request fields
Removal of existing endpoints

Non-breaking changes

Adding new optional response fields
Adding new endpoints
Adding new optional query parameters
Adding new optional request body fields
Expanding enum values in new fields

Deprecations

Deprecations are announced via a Deprecation header in affected API responses and in the changelog. Deprecated endpoints remain available for a minimum of 90 days after the announcement. Watch the Deprecation header in your HTTP client to catch these early.

Detecting the API version in your client

// After any fetch call, check the version header:
const response = await fetch("https://api.fyxvo.com/v1/...", { /* ... */ });
const apiVersion = response.headers.get("X-Fyxvo-API-Version");
if (apiVersion && apiVersion !== "v1") {
  // Version mismatch — review the changelog for migration steps
}

// curl: observe the header in verbose output
curl -I https://api.fyxvo.com/health
# X-Fyxvo-API-Version: v1

Section 10

Troubleshooting

A detailed diagnostic guide for the most common failure categories.

401 / 403

Authentication Errors

The gateway or API rejected your credentials. This covers both missing-token (401) and insufficient-scope (403) failures.

Causes

JWT has expired (tokens expire after 24 hours)
API key was revoked or does not exist
Key is missing required scope (rpc:request for standard, priority:relay for priority)

Diagnosis

Check the error.code field in the response body. Code TOKEN_EXPIRED means re-authenticate. Code INSUFFICIENT_SCOPE means generate a new key with the right scopes.

Fix

Re-authenticate via POST /v1/auth/challenge + POST /v1/auth/verify
Generate a new API key from the API Keys page with the required scopes
Confirm the X-Api-Key or Authorization: Bearer header is present and correctly formatted

Example: re-authenticate

# Step 1 — get a challenge
curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

# Step 2 — sign the returned message with your wallet and verify
curl -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET","message":"<from-step-1>","signature":"<base58-sig>"}'

network

Connection Errors

The request never reaches the gateway or returns a non-JSON response.

Causes

Wrong endpoint URL (common: using API base instead of gateway base)
No internet access or DNS resolution failure
Gateway is temporarily unavailable (planned maintenance or incident)

Fix

Verify the RPC endpoint: https://rpc.fyxvo.com/rpc
Check status.fyxvo.com for active incidents

Example: health check

curl https://rpc.fyxvo.com/health
# Expected: {"status":"ok"}

curl https://api.fyxvo.com/health
# Expected: {"status":"ok"}

429

Rate Limit Errors

The gateway returned a 429 Too Many Requests. Your project has exceeded its per-minute request quota.

Causes

Burst of requests exceeded the per-minute limit for your tier
Multiple clients sharing the same API key concurrently
Missing backoff logic causing retry storms

Diagnosis

Check the X-RateLimit-Remaining and Retry-After headers on the 429 response.

Fix

Implement exponential backoff using the Retry-After header value
Consider upgrading to the Priority tier for higher throughput limits
Deduplicate requests and use batch methods where available

Example: check rate limit headers

curl -i -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

# Look for: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

402

Balance Errors

A 402 Payment Required means the project does not have enough SOL credits to cover the relay request.

Causes

Project treasury balance has been exhausted
Funding transaction was sent but not yet verified by the API
Using a key from a different project with an empty treasury

Fix

Fund the project at fyxvo.com/funding
Verify a pending funding transaction using POST /v1/projects/:id/funding/:fid/verify

Example: check balance via API

curl https://api.fyxvo.com/v1/me/balance \
  -H "authorization: Bearer YOUR_JWT"

# Returns: { "availableSolCredits": "...", "totalSolFunded": "..." }

RPC

Unexpected RPC Errors

The gateway reached Solana devnet but the RPC call itself failed. Check the fyxvo_hint field in the error response for a human-readable diagnosis.

Causes

Solana devnet node under load or temporarily unavailable
Blockhash has expired before the transaction was submitted (use getLatestBlockhash again)
Transaction simulation failed due to an account constraint or insufficient lamports

Common codes

-32002 — Transaction simulation failed: check transaction logs in the response
-32003 — Blockhash expired: fetch a fresh blockhash and re-sign
-32016 — Blockhash not found: same resolution as -32003

Example: inspect fyxvo_hint

# A Fyxvo error response looks like:
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Transaction simulation failed",
    "fyxvo_hint": "The transaction failed simulation. Check that the fee payer has enough SOL and all accounts are valid."
  }
}

Reference

Error Reference

A quick reference for every error code returned by the Fyxvo API and gateway.

All Fyxvo API errors follow the shape { error: string, message: string }. HTTP status codes map directly to problem categories: 400 for validation, 401 for auth, 402 for insufficient balance, 403 for scope or role issues, 429 for rate limits, and 503 for protocol unavailability. See the Error Codes table below for the full list with resolution guidance.

Reference

CI/CD Integration

How to use Fyxvo API keys safely in automated pipelines.

Store your API key in an environment secret (e.g. FYXVO_API_KEY) and pass it as the X-Api-Key header. In GitHub Actions, use ${{ secrets.FYXVO_API_KEY }}. Never commit keys directly. Use separate keys per environment so you can revoke CI access without affecting production.

Reference

Migration Guide

Switch to Fyxvo from Helius, QuickNode, or any other Solana RPC provider.

Fyxvo is a drop-in replacement for any standard Solana JSON-RPC provider. Replace your existing endpoint URL with the Fyxvo gateway URL and add an X-Api-Key header containing your relay key. No SDK changes are required — any library that speaks JSON-RPC over HTTP works without modification.

Section 11

Network Status

How to check the live condition of the API, gateway, and protocol.

Health check commands

# API health
curl https://api.fyxvo.com/health
# { "status": "ok", "timestamp": "..." }

# Gateway health
curl https://rpc.fyxvo.com/health
# { "status": "ok" }

# Gateway full status (metrics, node count, pricing)
curl https://rpc.fyxvo.com/v1/status

# Status page
open https://status.fyxvo.com

status.fyxvo.com

https://status.fyxvo.com

Public status page. Combines API health, gateway health, and protocol readiness into a single honest surface. Share this with teammates during evaluation.

API health

https://api.fyxvo.com/health

Returns { "status": "ok" } when the control plane, database, and Redis are operational. Include this in your monitoring setup.

Gateway status

https://rpc.fyxvo.com/v1/status

Returns the full gateway state: node count, upstream availability, pricing config, scope enforcement status, and live relay metrics.

Interpreting a degraded status

If the status page shows degraded, check individual health endpoints to isolate whether the issue is the API, gateway, or Solana devnet itself. If devnet is healthy but the gateway is degraded, contact support before scaling traffic.

Section 12

Changelog

What shipped in each version of the Fyxvo devnet platform.

Version 0.1.0

current

Initial devnet launch release

Wallet authentication

Challenge–sign–verify JWT flow. Supports Phantom, Solflare, Backpack, and Wallet Standard adapters.

Project activation

On-chain project account creation via Anchor PDA derivation. Wallet signs the activation transaction; API verifies confirmation.

SOL funding

API-prepared unsigned transactions for SOL deposits into the Anchor-managed project vault. Includes verify endpoint for balance refresh.

Standard relay

JSON-RPC relay at /rpc with API key validation, funded balance enforcement, multi-node routing, and fallback.

Priority relay

Separate /priority path with priority:relay scope requirement, independent rate window, and distinct pricing from standard.

Analytics

Overview endpoint for cross-project totals and per-project endpoint for method breakdown, latency, and error log.

Per-key analytics

Request counts and success rates broken down by individual API key so teams can trace which key is responsible for traffic.

Method breakdown

Analytics surface includes per-method request counts and average latency to identify expensive or high-volume RPC methods.

Error log

Recent error events surfaced in the analytics API with timestamps, error codes, and affected project identifiers.

Notifications

In-product notification surface for balance warnings, rate limit events, and project status changes.

View the full changelog →

Migration

Migrating from Helius or QuickNode

Switch to Fyxvo in two lines of code. No SDK changes required.

Fyxvo is a drop-in Solana RPC provider. Replace the endpoint URL and add your API key header. Everything else stays the same.

Before (Helius / QuickNode / any provider)

const connection = new Connection("https://mainnet.helius-rpc.com/?api-key=YOUR_KEY");
// or
const connection = new Connection("https://solana-mainnet.quiknode.pro/YOUR_KEY/");

After (Fyxvo)

const connection = new Connection("https://rpc.fyxvo.com/rpc", {
  httpHeaders: { "X-Api-Key": "fyxvo_live_YOUR_KEY" }
});

What stays the same

All Solana JSON-RPC methods work identically
@solana/web3.js, solana-py, and all standard clients
Transaction signing and submission flows
WebSocket subscriptions (coming soon)

What is different

Authentication uses a per-project API key in the X-Api-Key header (not a URL query param)
Billing is on-chain: SOL credits are funded directly to your project treasury
Currently devnet only — mainnet is on the roadmap

Reference

Rate limits reference

Per-key rate limits on devnet. Limits will increase as the network scales.

Path	Scope required	Limit	Window
/rpc (standard)	rpc:request	300 req	60 s
/priority (priority)	priority:relay	60 req	60 s
API (auth, projects)	n/a (JWT)	120 req	60 s
API (analytics)	n/a (JWT)	120 req	60 s

Rate limit headers: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset. On 429, wait for the reset timestamp before retrying.

Reference

Error codes reference

Common error codes returned by the API and gateway.

HTTP	Code	Meaning	Resolution
400	validation_error	Request body failed schema validation	Check the details field for which fields are invalid
400	invalid_message	Auth challenge message does not match	Request a new challenge and sign the exact returned message
401	unauthorized	No JWT token provided	Include Authorization: Bearer <token> header
401	invalid_token	JWT is malformed or expired	Re-authenticate via /v1/auth/challenge + /v1/auth/verify
401	invalid_signature	Wallet signature verification failed	Sign with the correct wallet and the exact challenge message
401	session_expired	Session version has been rotated	Re-authenticate to get a fresh JWT
402	insufficient_balance	Project has no spendable SOL credits	Fund the project treasury and wait for confirmation
403	forbidden	Action requires elevated privileges	Check your account role in Settings
403	scope_missing	API key lacks the required scope	Revoke the key and create a new one with the correct scopes
404	not_found	Project, key, or resource not found	Verify the ID is correct and belongs to your account
409	project_already_activated	Activation transaction already confirmed	The project is already active — no action needed
429	rate_limited	Rate limit exceeded for this window	Back off and retry after x-ratelimit-reset timestamp
503	protocol_not_ready	Fyxvo program not ready on chain	Check /status for protocol readiness details

FAQ

Frequently asked questions

Real questions from developers integrating with Fyxvo.

Is Fyxvo production-ready for mainnet?

Not yet. Fyxvo is currently a private devnet alpha. Mainnet support is on the roadmap. Devnet-graduated projects will have a clear migration path when mainnet launches.

What happens if my SOL balance runs out?

Gateway requests will return a 402 Insufficient Balance error until you fund the project treasury. Your project data, API keys, and analytics are preserved — only relay access is paused.

Can I use Fyxvo without a wallet?

No. Wallet ownership is the authentication anchor. You need a Solana wallet (Phantom, Backpack, etc.) to create a project, fund the treasury, and receive a session JWT.

How do I get more devnet SOL for testing?

Use the Solana devnet faucet: `solana airdrop 2 YOUR_WALLET --url devnet`. You can also use https://faucet.solana.com. Note: devnet SOL has no real value.

What RPC methods are compute-heavy and cost more?

The following methods cost 3,000 lamports instead of 1,000: getProgramAccounts, getLargestAccounts, getSignaturesForAddress, getSignaturesForAddress2, getTokenLargestAccounts. These are expensive upstream queries that require heavier node compute.

Can I have multiple projects?

Yes. Each project is an independent on-chain account with its own treasury, API keys, and analytics. Create additional projects from the Dashboard.

How do volume discounts work?

Discounts apply to your billing rate: ≥1M requests/month → 20% off standard rate; ≥10M requests/month → 40% off. During devnet alpha, contact the team to apply volume pricing manually.

Why does the gateway return a 401 even with a valid API key?

The most common causes: (1) the key was revoked, (2) the key lacks the required scope (rpc:request for standard, priority:relay for priority), or (3) the X-Api-Key header is missing or misspelled.

Can I use Fyxvo with languages other than JavaScript?

Yes. Any HTTP client works. Use the X-Api-Key header and POST JSON-RPC to the gateway endpoint. Python, Rust, Go, and curl all work identically.

How do I withdraw unused SOL from my project treasury?

Treasury withdrawal is not yet available via the dashboard UI. During the devnet alpha, contact the team to initiate a withdrawal. Mainnet will have a self-serve withdrawal flow.

Reference

RPC Reference

A glossary of key Solana JSON-RPC methods routed through the Fyxvo gateway.

Account & Balance

getBalanceStandard[pubkey]

Returns the lamport balance of the account at the given public key.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa"]}'

getAccountInfoStandard[pubkey]

Returns all information associated with the account at the given public key.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa",{"encoding":"base58"}]}'

getMultipleAccountsStandard[pubkeys[]]

Get info for multiple accounts at once.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMultipleAccounts","params":[["PUBKEY1","PUBKEY2"],{"encoding":"base58"}]}'

getTokenAccountBalanceStandard[pubkey]

Get token account balance for an SPL Token account.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountBalance","params":["TOKEN_ACCOUNT_PUBKEY"]}'

getTokenAccountsByOwnerStandard[ownerAddress, { mint | programId }]

Get all token accounts owned by an address, filtered by mint or program ID.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountsByOwner","params":["OWNER_PUBKEY",{"programId":"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},{"encoding":"jsonParsed"}]}'

getTokenLargestAccountsStandard[mintAddress]

Get the 20 largest token accounts for a given mint.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenLargestAccounts","params":["MINT_ADDRESS"]}'

getTokenSupplyStandard[mintAddress]

Get the total supply of an SPL Token mint.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenSupply","params":["MINT_ADDRESS"]}'

getProgramAccountsStandard⚡ Heavy[programId]

Get all accounts owned by a program. Compute-heavy — use filters to narrow results.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getProgramAccounts","params":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]}'

Block & Slot

getSlotStandard

Returns the slot that has reached the given or default commitment level.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

getBlockStandard⚡ Heavy[slot]

Returns identity and transaction information about a confirmed block in the ledger. Compute-heavy.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlock","params":[SLOT_NUMBER,{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getLatestBlockhashStandard

Returns the latest blockhash and the last block height at which it is valid.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash","params":[{"commitment":"confirmed"}]}'

getBlockHeightStandard

Returns the current block height of the node.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockHeight","params":[]}'

getBlockTimeStandard[slot]

Get estimated production time of a block, as Unix timestamp.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockTime","params":[SLOT_NUMBER]}'

getBlocksStandard[startSlot, endSlot?]

Get confirmed blocks in a slot range.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlocks","params":[START_SLOT,END_SLOT]}'

getFirstAvailableBlockStandard

Get the slot of the lowest confirmed block that has not been purged from the ledger.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getFirstAvailableBlock","params":[]}'

Transaction

sendTransactionPriority[encodedTransaction]

Submits a signed transaction to the cluster for processing.

Example

curl -X POST https://rpc.fyxvo.com/priority \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["<base64-signed-tx>",{"encoding":"base64","skipPreflight":false}]}'

simulateTransactionPriority[transaction]

Simulate sending a transaction without actually submitting it to the network.

Example

curl -X POST https://rpc.fyxvo.com/priority \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"simulateTransaction","params":["<base64-tx>",{"encoding":"base64","sigVerify":false}]}'

getTransactionStandard[signature]

Returns transaction details for a confirmed transaction.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":["SIGNATURE",{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getTransactionsStandard[signatures[]]

Get details for multiple transactions by signature array.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransactions","params":[["SIG1","SIG2"],{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getSignaturesForAddressStandard[address]

Get confirmed signatures for transactions involving an address.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignaturesForAddress","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa",{"limit":10}]}'

getSignatureStatusesStandard[signatures[]]

Returns the statuses of a list of transaction signatures.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignatureStatuses","params":[["SIG1","SIG2"],{"searchTransactionHistory":false}]}'

Network

getHealthStandard

Returns the current health of the node — “ok” if healthy.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

getVersionStandard

Returns the current Solana version running on the node.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getVersion","params":[]}'

getEpochInfoStandard

Returns information about the current epoch including slot index and epoch number.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getEpochInfo","params":[]}'

getEpochScheduleStandard

Get epoch schedule information from the cluster’s genesis config.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getEpochSchedule","params":[]}'

getGenesisHashStandard

Returns the genesis hash of the ledger.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getGenesisHash","params":[]}'

getClusterNodesStandard

Get information about all cluster nodes participating in the network.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getClusterNodes","params":[]}'

getLeaderScheduleStandard

Get the leader schedule for the current or a specific epoch.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLeaderSchedule","params":[]}'

getMinimumBalanceForRentExemptionStandard[dataSize]

Get minimum balance required to make account rent exempt for a given data size.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMinimumBalanceForRentExemption","params":[128]}'

getRecentPerformanceSamplesStandard[limit?]

Get recent performance samples showing transactions and slots per second.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getRecentPerformanceSamples","params":[5]}'

getStakeActivationStandard[pubkey]

Get epoch activation information for a stake account.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getStakeActivation","params":["STAKE_ACCOUNT_PUBKEY"]}'

getVoteAccountsStandard

Get account info and stake for all voting accounts in the current bank.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getVoteAccounts","params":[]}'

Still have questions?

Docs cover the fastest self-serve path. For launch-fit questions, issue reports, or managed rollout conversations, use the community paths or the contact page.

X Discord Telegram

Docs

Start from wallet auth to first request in minutes.

This guide covers the full self-serve path on Fyxvo devnet. Wallet auth, project activation, SOL funding, relay usage, analytics, and SDK reference — all in one place.

Devnet only

Fyxvo is live on Solana devnet today. SOL is the active funding path. USDC remains intentionally configuration-gated until it is explicitly enabled for a deployment.

Need a direct line while integrating?

For launch-fit questions, issue reports, or managed rollout conversations, use the community paths below or the contact page.

X Discord Telegram

Section 1

Introduction

What Fyxvo is, who it is for, and what is live on devnet today.

What is Fyxvo

A developer platform for Solana teams that need a real, funded RPC relay path — not a mock dashboard.

Who it is for

Solana teams validating funded RPC, priority relay, and analytics before widening traffic.

What is live today

The full devnet path is active: wallet auth, project activation, SOL funding, standard relay, priority relay, analytics, and public status.

Section 2

Quickstart

The four-step path from wallet connect to first confirmed relay request.

Step 1

Connect a wallet

Step 2

Create and activate a project

Step 3

Fund with SOL

Step 4

Issue a key and send traffic

Generate a relay key scoped to rpc:request. Copy the /rpc endpoint and send a small JSON-RPC request. That first request should appear in project analytics and on the status surface within seconds.

Complete working example

Five Minute Quickstart

From zero to a live devnet relay request using curl only. No SDK required.

Step 1 — Request an auth challenge

curl -s -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET_ADDRESS_BASE58"}'

# Save the nonce and message from the response
# { "walletAddress": "...", "nonce": "abc123", "message": "Fyxvo Authentication\nWallet: ...\nNonce: abc123\n..." }

Step 2 — Sign the message with your wallet CLI (e.g. solana-keygen)

# Sign the exact message string returned from the challenge endpoint.
# Using the Solana CLI (base58 output):
echo -n "Fyxvo Authentication\nWallet: YOUR_WALLET\nNonce: abc123\n..." | \
  solana sign-offchain-message - --keypair ~/.config/solana/id.json

# Or use @solana/wallet-adapter-base in the browser:
# const sig = await wallet.signMessage(Buffer.from(message));
# const sigBase58 = bs58.encode(sig);

Step 3 — Verify and get your JWT

curl -s -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "walletAddress": "YOUR_WALLET_ADDRESS_BASE58",
    "message": "THE_EXACT_CHALLENGE_MESSAGE",
    "signature": "YOUR_BASE58_SIGNATURE"
  }'

# { "token": "eyJhbGci...", "user": { "walletAddress": "...", "role": "MEMBER" } }
export JWT="eyJhbGci..."

Step 4 — Issue an API key (after creating and funding a project in the dashboard)

curl -s -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/api-keys \
  -H "authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -d '{"label":"my-key","scopes":["project:read","rpc:request"]}'

# { "item": { "id": "...", "prefix": "fyxvo_live_...", ... }, "plainTextKey": "fyxvo_live_...secret" }
export API_KEY="fyxvo_live_...secret"

Step 5 — Send your first relay request

curl -s -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# { "jsonrpc": "2.0", "result": "ok", "id": 1 }

# Priority relay (requires priority:relay scope):
curl -s -X POST https://rpc.fyxvo.com/priority \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

That's it

Quickstarts

Framework Quickstarts

Ready-to-run examples for the most common Solana development environments.

Server component example using @solana/web3.js in a Next.js App Router route handler.

app/api/solana/route.ts

// app/api/solana/route.ts
import { Connection } from "@solana/web3.js";

const connection = new Connection(
  `https://rpc.fyxvo.com/rpc?api-key=${process.env.FYXVO_API_KEY}`
);

export async function GET() {
  const slot = await connection.getSlot();
  return Response.json({ slot });
}

Section 3

Authentication

Wallet-signed JWT flow: challenge, sign, verify.

How the wallet session works

Step 1 — Request a challenge

curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

Step 2 — Sign in the browser

Use wallet.signMessage(Buffer.from(challenge)) from @solana/wallet-adapter-base. Convert the resulting Uint8Array signature to base58 before sending.

Full auth flow

# 1. Get challenge — returns the exact message to sign
curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

# Response: { "walletAddress": "...", "nonce": "...", "message": "fyxvo:YOUR_WALLET:NONCE" }

# 2. Sign the message with your wallet (browser, @solana/wallet-adapter-base)
const encoded = new TextEncoder().encode(message);
const signatureBytes = await wallet.signMessage(encoded);
const signature = bs58.encode(signatureBytes);

# 3. Verify signature and receive JWT
curl -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "walletAddress": "YOUR_WALLET",
    "message": "<message-from-step-1>",
    "signature": "<base58-signature>"
  }'

# Response: { "token": "eyJ...", "user": { "id": "...", "walletAddress": "...", "role": "MEMBER" } }

JWT expiry

Tokens expire after 24 hours. Re-authenticate by repeating the challenge + verify flow. There is no refresh token endpoint; the wallet signs a new challenge each time.

Supported wallets

Phantom, Solflare, Backpack, and any Wallet Standard compatible wallet work through the Solana wallet adapter layer. Phantom is the fastest for browser-first devnet usage.

Section 4

Funding

SOL funding flow on devnet — prepare, sign, verify.

SOL is live on devnet

Prepare, sign, and verify a funding transaction

# 1. Prepare the unsigned funding transaction
curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/funding/prepare \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"asset":"SOL","amountLamports":100000000,"funderWalletAddress":"YOUR_WALLET"}'

# Response: { "item": { "id": "FUNDING_ID", "transactionBase64": "<unsigned-tx>", "amount": "100000000" } }

# 2. Decode, sign, and broadcast (using @solana/web3.js)
import { Transaction, Connection } from "@solana/web3.js";

const fundingItem = response.item;
const tx = Transaction.from(Buffer.from(fundingItem.transactionBase64, "base64"));
const signed = await wallet.signTransaction(tx);
const connection = new Connection("https://api.devnet.solana.com");
const sig = await connection.sendRawTransaction(signed.serialize());
await connection.confirmTransaction(sig, "confirmed");

# 3. Verify the confirmed transaction with the API
curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/funding/FUNDING_ID/verify \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"signature": "<tx-signature>"}'

Unsigned transaction review

The API returns the unsigned transaction encoded in base64. Decode and inspect it before signing. This keeps the funding flow explicit and auditable.

USDC stays gated

USDC funding exists in the protocol but is configuration-gated. It will not accept USDC transfers until the deployment explicitly enables it via runtime config.

Section 5

Standard RPC

Send standard JSON-RPC traffic through the /rpc relay endpoint.

Required scope

Keys used on the standard path must carry the rpc:request scope. Under-scoped keys receive a 403, not silent broad access.

Standard relay request

# Standard relay — requires rpc:request scope
curl -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

# Also accepts Authorization: Bearer
curl -X POST https://rpc.fyxvo.com/rpc \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash","params":[{"commitment":"confirmed"}]}'

What the gateway does

Validates the API key and checks its scope
Checks the project's funded SOL balance against the request cost
Routes to the upstream Solana RPC node pool with fallback
Logs the request, latency, and result for analytics rollups
Deducts the lamport cost from the project balance

Endpoint

Standard path: https://rpc.fyxvo.com/rpc

Section 6

Priority Relay

Latency-sensitive traffic on the /priority endpoint with a separately scoped key.

Required scope

Priority keys must carry both rpc:request and priority:relay scopes. Sending a standard key to /priority returns 403.

Priority relay request

# Priority relay — requires rpc:request AND priority:relay scopes
curl -X POST https://rpc.fyxvo.com/priority \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["<base64-tx>",{"encoding":"base64","skipPreflight":false}]}'

Standard vs priority

Property	Standard	Priority
Endpoint	/rpc	/priority
Scope	rpc:request	+ priority:relay
Rate limit	300 / min	60 / min

Why they are separate

Section 7

Analytics

Monitor request volume, latency, and errors across your Fyxvo projects.

Section 7

Analytics API

Fetch usage data across all projects or drill into a specific project.

GET https://api.fyxvo.com/v1/analytics/overview

curl https://api.fyxvo.com/v1/analytics/overview \
  -H "authorization: Bearer YOUR_JWT"

# Response shape:
# {
#   "item": {
#     "totals": { "projects": 3, "apiKeys": 5, "fundingRequests": 2, "requestLogs": 14200 },
#     "latency": { "averageMs": 42, "maxMs": 312 },
#     "requestsByService": [{ "service": "gateway", "count": 14200 }]
#   }
# }

GET https://api.fyxvo.com/v1/analytics/projects/:id

curl https://api.fyxvo.com/v1/analytics/projects/YOUR_PROJECT_ID?range=24h \
  -H "authorization: Bearer YOUR_JWT"

# Range options: 1h | 6h | 24h | 7d | 30d (default: all time)
# Response shape:
# {
#   "item": {
#     "totals": { "requestLogs": 4800, "apiKeys": 2, "fundingRequests": 1 },
#     "latency": { "averageMs": 38, "maxMs": 210, "p95Ms": 95 },
#     "statusCodes": [{ "statusCode": 200, "count": 4750 }, { "statusCode": 429, "count": 50 }],
#     "recentRequests": [{ "route": "/rpc", "method": "POST", "statusCode": 200, "durationMs": 38 }]
#   }
# }

Overview endpoint

Aggregates totals across all projects owned by the authenticated wallet: total requests, success rate, average latency, and 24-hour rolling count.

Project endpoint

Returns per-project metrics including method breakdown, recent error log, and latency percentiles for both standard and priority paths.

Auth required

Both endpoints require a valid JWT Bearer token in the Authorization header. Use the wallet auth flow to obtain one.

Project API

Public Stats API

Read project-level public stats with a project-scoped API key from your backend services.

Keep keys off the client

Pass x-api-key from a backend service, serverless function, or CI job. Do not ship project keys in browser bundles.

curl

curl https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public \
  -H "x-api-key: $FYXVO_API_KEY"

JavaScript fetch (server-side)

const response = await fetch("https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public", {
  headers: {
    "x-api-key": process.env.FYXVO_API_KEY!,
  },
  cache: "no-store",
});

const stats = await response.json();
console.log(stats);

Node.js

import process from "node:process";

const response = await fetch("https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public", {
  headers: {
    "x-api-key": process.env.FYXVO_API_KEY ?? "",
  },
});

console.log(await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/stats/public",
    headers={"x-api-key": os.environ["FYXVO_API_KEY"]},
    timeout=10,
)

print(response.json())

Interactive

API Explorer

Try live API endpoints directly from the docs. Paste your JWT token to test authenticated routes.

API Explorer

GET/health

Check API service health and database connectivity.

curl

curl https://api.fyxvo.com/health \
  -H "Content-Type: application/json"

Platform

Webhooks

Receive HTTP POST callbacks when events happen in your project.

Webhooks let you integrate Fyxvo events into your own systems. Every delivery includes an x-fyxvo-signature header with format sha256=<hex>.

Supported events

funding.confirmedapikey.createdapikey.revokedbalance.lowproject.activated

Create a webhook

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/webhooks \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"url":"https://your-server.example.com/webhook","events":["funding.confirmed","balance.low"]}'

Test a webhook

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/webhooks/WEBHOOK_ID/test \
  -H "authorization: Bearer YOUR_JWT"

Signature verification (Node.js)

const crypto = require('crypto');
const sig = req.headers['x-fyxvo-signature'];
const computed = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (sig !== computed) return res.status(401).send('Unauthorized');

Retry behavior

Platform

Team Collaboration

Invite team members to your project by Solana wallet address.

Project owners can invite other Fyxvo users by wallet address. Invitations are pending until the invitee accepts via PATCH /v1/projects/:id/members/:memberId/accept.

Member permissions

Members can view analytics and API keys but cannot delete the project or change ownership. Only the project owner can invite or remove members.

Team management

Team management is in Settings → Team on the project page. Pending invitations are shown until accepted or removed.

Invite a member

curl -X POST https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/members/invite \
  -H "authorization: Bearer YOUR_JWT" \
  -H "content-type: application/json" \
  -d '{"walletAddress":"MEMBER_WALLET_ADDRESS"}'

List members

curl https://api.fyxvo.com/v1/projects/YOUR_PROJECT_ID/members \
  -H "authorization: Bearer YOUR_JWT"

Platform

Public Project Pages

Share your project's aggregate stats publicly — no API key required.

README badge

Add a live status badge to your GitHub README. The badge shows latency and updates every 5 minutes via CDN cache.

README badge markdown

[![Fyxvo Status](https://api.fyxvo.com/badge/project/YOUR_SLUG)](https://www.fyxvo.com/p/YOUR_SLUG)

Playground

The API Playground lets you send live JSON-RPC requests to the Fyxvo gateway and inspect responses without writing any code.

Compare Mode

Toggle Compare in the request builder to run the same request on both the standard and priority paths simultaneously. The priority response badge turns green when it is faster.

Schema Panel

Click Schema next to any method to see the expected response shape — field names, types, and descriptions — before you send the request.

Shareable URLs

Click Share to encode the current method and parameters into the URL. Send the link to a colleague and they will land on the same request configuration.

Section 8

SDK Reference

@fyxvo/sdk — TypeScript SDK for the Fyxvo gateway and control-plane API.

SDK install

npm

npm install @fyxvo/sdk

yarn

yarn add @fyxvo/sdk

pnpm

pnpm add @fyxvo/sdk

Create a client

import { createFyxvoClient } from "@fyxvo/sdk";

const client = createFyxvoClient({
  baseUrl: "https://rpc.fyxvo.com",
  apiKey: process.env.FYXVO_API_KEY,
});

client.rpc() — standard relay

// Standard RPC request
const health = await client.rpc({
  id: 1,
  method: "getHealth",
});

// With params
const blockhash = await client.rpc({
  id: 2,
  method: "getLatestBlockhash",
  params: [{ commitment: "confirmed" }],
});

console.log(blockhash.result.value.blockhash);

client.rpc() with /priority path — priority relay

// Priority relay request (requires priority:relay scoped key)
// Pass the /priority path via the options second argument
const slot = await client.rpc(
  { id: 1, method: "getSlot" },
  { path: "/priority" }
);

if ("result" in slot) {
  const slotNumber = slot.result as number;
  // use slotNumber
}

Error handling

import { FyxvoError, FyxvoApiError } from "@fyxvo/sdk";

try {
  const result = await client.rpc({ id: 1, method: "getHealth" });
} catch (err) {
  if (err instanceof FyxvoApiError) {
    // HTTP-level error from the gateway (4xx / 5xx)
    // err.status holds the HTTP status code, err.message has the description
    const status: number | undefined = err.status;
    const message: string = err.message;
    void status; void message;
  } else if (err instanceof FyxvoError) {
    // SDK-level error (network, timeout, config)
    const message: string = err.message;
    void message;
  }
}

TypeScript — full wallet auth flow

import { createFyxvoClient } from "@fyxvo/sdk";

// Step 1 — request a challenge
const api = createFyxvoClient({ baseUrl: "https://api.fyxvo.com" });
const challenge = await api.request<{ message: string; nonce: string }>({
  method: "POST",
  path: "/v1/auth/challenge",
  body: { walletAddress: "YOUR_WALLET_ADDRESS" },
});

// Step 2 — sign the message with your wallet
const encoded = new TextEncoder().encode(challenge.message);
const sigBytes = await wallet.signMessage(encoded);
const signature = bs58.encode(sigBytes);

// Step 3 — verify and receive a JWT
const session = await api.request<{ token: string }>({
  method: "POST",
  path: "/v1/auth/verify",
  body: {
    walletAddress: "YOUR_WALLET_ADDRESS",
    message: challenge.message,
    signature,
  },
});

// Step 4 — use the JWT as a bearer token for subsequent calls
const authedClient = createFyxvoClient({
  baseUrl: "https://api.fyxvo.com",
  headers: { authorization: `Bearer ${session.token}` },
});

TypeScript — create an API key

// Create a gateway relay API key (requires JWT from auth flow)
const authedClient = createFyxvoClient({
  baseUrl: "https://api.fyxvo.com",
  headers: { authorization: "Bearer YOUR_JWT" },
});

const created = await authedClient.request<{
  item: { id: string; prefix: string; scopes: string[] };
  plainTextKey: string;
}>({
  method: "POST",
  path: "/v1/api-keys",
  body: { label: "my-relay-key", scopes: ["rpc:request"] },
});

const apiKey = created.plainTextKey;

TypeScript — typed gateway RPC call

import { createFyxvoClient, type RpcResponse } from "@fyxvo/sdk";

// Gateway client — use your relay API key here
const gateway = createFyxvoClient({
  baseUrl: "https://rpc.fyxvo.com",
  apiKey: process.env.FYXVO_API_KEY,
});

// Standard RPC call
const health = await gateway.rpc<string>({ method: "getHealth" });

// With typed params
interface BlockhashResult {
  blockhash: string;
  lastValidBlockHeight: number;
}
const response: RpcResponse<{ value: BlockhashResult }> = await gateway.rpc({
  id: 1,
  method: "getLatestBlockhash",
  params: [{ commitment: "confirmed" }],
});

if ("result" in response) {
  const blockhash: string = response.result.value.blockhash;
  void blockhash;
}

Python (requests) — gateway RPC call

import requests

response = requests.post(
    "https://rpc.fyxvo.com/rpc",
    headers={"x-api-key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "getHealth", "params": []}
)
print(response.json())

FyxvoError

Base class for all SDK errors. Covers network failures, timeouts, and configuration issues. Always catch this as a fallback.

FyxvoApiError

Extends FyxvoError with an HTTP statusCode. Thrown when the gateway or API returns a 4xx or 5xx response. Check statusCode === 429 for rate limit handling.

Section 9

Rate Limits

Per-key limits for standard and priority paths, and how to handle 429 responses.

Standard path

Limit: 300 requests per 60-second window

Scope: rpc:request

Enforcement: Redis-backed, per API key

Priority path

Limit: 60 requests per 60-second window

Scope: priority:relay

Enforcement: Separate window from standard

429 handling with exponential backoff

# The gateway returns 429 when a key exceeds its rate window.
# Response headers include:
#   x-ratelimit-limit:     <requests per window>
#   x-ratelimit-remaining: <remaining in current window>
#   x-ratelimit-reset:     <unix timestamp when the window resets>

# Standard path (rpc:request scope) — 300 req / 60 s per key
# Priority path (priority:relay scope) — 60 req / 60 s per key

# Retry with backoff after a 429:
async function withRetry(fn, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err?.statusCode === 429 && attempt < maxAttempts - 1) {
        await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
      } else {
        throw err;
      }
    }
  }
}

Rate limit headers

Every response includes x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. Use these to implement adaptive backoff without waiting for a 429.

Gateway

Simulation Mode

Test against the gateway without using your project balance or touching Solana devnet.

What simulation mode does

Requests are free — no lamports are deducted.
Traffic is not forwarded to Solana devnet.
The gateway returns canned, deterministic responses.
Useful for SDK integration tests and CI pipelines.

Supported methods

getHealth
getSlot
getBalance
getLatestBlockhash

Other methods may pass through or return a stub error in simulation mode.

Enable simulation mode — append ?simulate=true

# Standard path with simulation enabled
curl -X POST "https://rpc.fyxvo.com/rpc?simulate=true" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

# Response (canned — not from devnet):
# {"jsonrpc":"2.0","id":1,"result":"ok"}

Production integrations

Reference

API Versioning

How Fyxvo versions its REST API and what counts as a breaking change.

Current version

Version: v1

Base path: /v1/

Version header: X-Fyxvo-API-Version: v1

Version detection

Every API response includes the X-Fyxvo-API-Version: v1 header. Check this header in your client to detect version mismatches before they cause silent behavior changes.

Breaking changes

Changes to existing response field shapes or types
Removal of response fields
Changes to the authentication mechanism
Changes to required request fields
Removal of existing endpoints

Non-breaking changes

Adding new optional response fields
Adding new endpoints
Adding new optional query parameters
Adding new optional request body fields
Expanding enum values in new fields

Deprecations

Detecting the API version in your client

// After any fetch call, check the version header:
const response = await fetch("https://api.fyxvo.com/v1/...", { /* ... */ });
const apiVersion = response.headers.get("X-Fyxvo-API-Version");
if (apiVersion && apiVersion !== "v1") {
  // Version mismatch — review the changelog for migration steps
}

// curl: observe the header in verbose output
curl -I https://api.fyxvo.com/health
# X-Fyxvo-API-Version: v1

Section 10

Troubleshooting

A detailed diagnostic guide for the most common failure categories.

401 / 403

Authentication Errors

The gateway or API rejected your credentials. This covers both missing-token (401) and insufficient-scope (403) failures.

Causes

JWT has expired (tokens expire after 24 hours)
API key was revoked or does not exist
Key is missing required scope (rpc:request for standard, priority:relay for priority)

Diagnosis

Check the error.code field in the response body. Code TOKEN_EXPIRED means re-authenticate. Code INSUFFICIENT_SCOPE means generate a new key with the right scopes.

Fix

Re-authenticate via POST /v1/auth/challenge + POST /v1/auth/verify
Generate a new API key from the API Keys page with the required scopes
Confirm the X-Api-Key or Authorization: Bearer header is present and correctly formatted

Example: re-authenticate

# Step 1 — get a challenge
curl -X POST https://api.fyxvo.com/v1/auth/challenge \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET"}'

# Step 2 — sign the returned message with your wallet and verify
curl -X POST https://api.fyxvo.com/v1/auth/verify \
  -H "content-type: application/json" \
  -d '{"walletAddress":"YOUR_WALLET","message":"<from-step-1>","signature":"<base58-sig>"}'

network

Connection Errors

The request never reaches the gateway or returns a non-JSON response.

Causes

Wrong endpoint URL (common: using API base instead of gateway base)
No internet access or DNS resolution failure
Gateway is temporarily unavailable (planned maintenance or incident)

Fix

Verify the RPC endpoint: https://rpc.fyxvo.com/rpc
Check status.fyxvo.com for active incidents

Example: health check

curl https://rpc.fyxvo.com/health
# Expected: {"status":"ok"}

curl https://api.fyxvo.com/health
# Expected: {"status":"ok"}

429

Rate Limit Errors

The gateway returned a 429 Too Many Requests. Your project has exceeded its per-minute request quota.

Causes

Burst of requests exceeded the per-minute limit for your tier
Multiple clients sharing the same API key concurrently
Missing backoff logic causing retry storms

Diagnosis

Check the X-RateLimit-Remaining and Retry-After headers on the 429 response.

Fix

Implement exponential backoff using the Retry-After header value
Consider upgrading to the Priority tier for higher throughput limits
Deduplicate requests and use batch methods where available

Example: check rate limit headers

curl -i -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

# Look for: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

402

Balance Errors

A 402 Payment Required means the project does not have enough SOL credits to cover the relay request.

Causes

Project treasury balance has been exhausted
Funding transaction was sent but not yet verified by the API
Using a key from a different project with an empty treasury

Fix

Fund the project at fyxvo.com/funding
Verify a pending funding transaction using POST /v1/projects/:id/funding/:fid/verify

Example: check balance via API

curl https://api.fyxvo.com/v1/me/balance \
  -H "authorization: Bearer YOUR_JWT"

# Returns: { "availableSolCredits": "...", "totalSolFunded": "..." }

RPC

Unexpected RPC Errors

The gateway reached Solana devnet but the RPC call itself failed. Check the fyxvo_hint field in the error response for a human-readable diagnosis.

Causes

Solana devnet node under load or temporarily unavailable
Blockhash has expired before the transaction was submitted (use getLatestBlockhash again)
Transaction simulation failed due to an account constraint or insufficient lamports

Common codes

-32002 — Transaction simulation failed: check transaction logs in the response
-32003 — Blockhash expired: fetch a fresh blockhash and re-sign
-32016 — Blockhash not found: same resolution as -32003

Example: inspect fyxvo_hint

# A Fyxvo error response looks like:
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Transaction simulation failed",
    "fyxvo_hint": "The transaction failed simulation. Check that the fee payer has enough SOL and all accounts are valid."
  }
}

Reference

Error Reference

A quick reference for every error code returned by the Fyxvo API and gateway.

Reference

CI/CD Integration

How to use Fyxvo API keys safely in automated pipelines.

Reference

Migration Guide

Switch to Fyxvo from Helius, QuickNode, or any other Solana RPC provider.

Section 11

Network Status

How to check the live condition of the API, gateway, and protocol.

Health check commands

# API health
curl https://api.fyxvo.com/health
# { "status": "ok", "timestamp": "..." }

# Gateway health
curl https://rpc.fyxvo.com/health
# { "status": "ok" }

# Gateway full status (metrics, node count, pricing)
curl https://rpc.fyxvo.com/v1/status

# Status page
open https://status.fyxvo.com

status.fyxvo.com

https://status.fyxvo.com

Public status page. Combines API health, gateway health, and protocol readiness into a single honest surface. Share this with teammates during evaluation.

API health

https://api.fyxvo.com/health

Returns { "status": "ok" } when the control plane, database, and Redis are operational. Include this in your monitoring setup.

Gateway status

https://rpc.fyxvo.com/v1/status

Returns the full gateway state: node count, upstream availability, pricing config, scope enforcement status, and live relay metrics.

Interpreting a degraded status

Section 12

Changelog

What shipped in each version of the Fyxvo devnet platform.

Version 0.1.0

current

Initial devnet launch release

Wallet authentication

Challenge–sign–verify JWT flow. Supports Phantom, Solflare, Backpack, and Wallet Standard adapters.

Project activation

On-chain project account creation via Anchor PDA derivation. Wallet signs the activation transaction; API verifies confirmation.

SOL funding

API-prepared unsigned transactions for SOL deposits into the Anchor-managed project vault. Includes verify endpoint for balance refresh.

Standard relay

JSON-RPC relay at /rpc with API key validation, funded balance enforcement, multi-node routing, and fallback.

Priority relay

Separate /priority path with priority:relay scope requirement, independent rate window, and distinct pricing from standard.

Analytics

Overview endpoint for cross-project totals and per-project endpoint for method breakdown, latency, and error log.

Per-key analytics

Request counts and success rates broken down by individual API key so teams can trace which key is responsible for traffic.

Method breakdown

Analytics surface includes per-method request counts and average latency to identify expensive or high-volume RPC methods.

Error log

Recent error events surfaced in the analytics API with timestamps, error codes, and affected project identifiers.

Notifications

In-product notification surface for balance warnings, rate limit events, and project status changes.

View the full changelog →

Migration

Migrating from Helius or QuickNode

Switch to Fyxvo in two lines of code. No SDK changes required.

Fyxvo is a drop-in Solana RPC provider. Replace the endpoint URL and add your API key header. Everything else stays the same.

Before (Helius / QuickNode / any provider)

const connection = new Connection("https://mainnet.helius-rpc.com/?api-key=YOUR_KEY");
// or
const connection = new Connection("https://solana-mainnet.quiknode.pro/YOUR_KEY/");

After (Fyxvo)

const connection = new Connection("https://rpc.fyxvo.com/rpc", {
  httpHeaders: { "X-Api-Key": "fyxvo_live_YOUR_KEY" }
});

What stays the same

All Solana JSON-RPC methods work identically
@solana/web3.js, solana-py, and all standard clients
Transaction signing and submission flows
WebSocket subscriptions (coming soon)

What is different

Authentication uses a per-project API key in the X-Api-Key header (not a URL query param)
Billing is on-chain: SOL credits are funded directly to your project treasury
Currently devnet only — mainnet is on the roadmap

Reference

Rate limits reference

Per-key rate limits on devnet. Limits will increase as the network scales.

Path	Scope required	Limit	Window
/rpc (standard)	rpc:request	300 req	60 s
/priority (priority)	priority:relay	60 req	60 s
API (auth, projects)	n/a (JWT)	120 req	60 s
API (analytics)	n/a (JWT)	120 req	60 s

Rate limit headers: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset. On 429, wait for the reset timestamp before retrying.

Reference

Error codes reference

Common error codes returned by the API and gateway.

HTTP	Code	Meaning	Resolution
400	validation_error	Request body failed schema validation	Check the details field for which fields are invalid
400	invalid_message	Auth challenge message does not match	Request a new challenge and sign the exact returned message
401	unauthorized	No JWT token provided	Include Authorization: Bearer <token> header
401	invalid_token	JWT is malformed or expired	Re-authenticate via /v1/auth/challenge + /v1/auth/verify
401	invalid_signature	Wallet signature verification failed	Sign with the correct wallet and the exact challenge message
401	session_expired	Session version has been rotated	Re-authenticate to get a fresh JWT
402	insufficient_balance	Project has no spendable SOL credits	Fund the project treasury and wait for confirmation
403	forbidden	Action requires elevated privileges	Check your account role in Settings
403	scope_missing	API key lacks the required scope	Revoke the key and create a new one with the correct scopes
404	not_found	Project, key, or resource not found	Verify the ID is correct and belongs to your account
409	project_already_activated	Activation transaction already confirmed	The project is already active — no action needed
429	rate_limited	Rate limit exceeded for this window	Back off and retry after x-ratelimit-reset timestamp
503	protocol_not_ready	Fyxvo program not ready on chain	Check /status for protocol readiness details

FAQ

Frequently asked questions

Real questions from developers integrating with Fyxvo.

Is Fyxvo production-ready for mainnet?

Not yet. Fyxvo is currently a private devnet alpha. Mainnet support is on the roadmap. Devnet-graduated projects will have a clear migration path when mainnet launches.

What happens if my SOL balance runs out?

Gateway requests will return a 402 Insufficient Balance error until you fund the project treasury. Your project data, API keys, and analytics are preserved — only relay access is paused.

Can I use Fyxvo without a wallet?

No. Wallet ownership is the authentication anchor. You need a Solana wallet (Phantom, Backpack, etc.) to create a project, fund the treasury, and receive a session JWT.

How do I get more devnet SOL for testing?

Use the Solana devnet faucet: `solana airdrop 2 YOUR_WALLET --url devnet`. You can also use https://faucet.solana.com. Note: devnet SOL has no real value.

What RPC methods are compute-heavy and cost more?

Can I have multiple projects?

Yes. Each project is an independent on-chain account with its own treasury, API keys, and analytics. Create additional projects from the Dashboard.

How do volume discounts work?

Discounts apply to your billing rate: ≥1M requests/month → 20% off standard rate; ≥10M requests/month → 40% off. During devnet alpha, contact the team to apply volume pricing manually.

Why does the gateway return a 401 even with a valid API key?

The most common causes: (1) the key was revoked, (2) the key lacks the required scope (rpc:request for standard, priority:relay for priority), or (3) the X-Api-Key header is missing or misspelled.

Can I use Fyxvo with languages other than JavaScript?

Yes. Any HTTP client works. Use the X-Api-Key header and POST JSON-RPC to the gateway endpoint. Python, Rust, Go, and curl all work identically.

How do I withdraw unused SOL from my project treasury?

Treasury withdrawal is not yet available via the dashboard UI. During the devnet alpha, contact the team to initiate a withdrawal. Mainnet will have a self-serve withdrawal flow.

Reference

RPC Reference

A glossary of key Solana JSON-RPC methods routed through the Fyxvo gateway.

Account & Balance

getBalanceStandard[pubkey]

Returns the lamport balance of the account at the given public key.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa"]}'

getAccountInfoStandard[pubkey]

Returns all information associated with the account at the given public key.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa",{"encoding":"base58"}]}'

getMultipleAccountsStandard[pubkeys[]]

Get info for multiple accounts at once.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMultipleAccounts","params":[["PUBKEY1","PUBKEY2"],{"encoding":"base58"}]}'

getTokenAccountBalanceStandard[pubkey]

Get token account balance for an SPL Token account.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountBalance","params":["TOKEN_ACCOUNT_PUBKEY"]}'

getTokenAccountsByOwnerStandard[ownerAddress, { mint | programId }]

Get all token accounts owned by an address, filtered by mint or program ID.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountsByOwner","params":["OWNER_PUBKEY",{"programId":"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},{"encoding":"jsonParsed"}]}'

getTokenLargestAccountsStandard[mintAddress]

Get the 20 largest token accounts for a given mint.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenLargestAccounts","params":["MINT_ADDRESS"]}'

getTokenSupplyStandard[mintAddress]

Get the total supply of an SPL Token mint.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenSupply","params":["MINT_ADDRESS"]}'

getProgramAccountsStandard⚡ Heavy[programId]

Get all accounts owned by a program. Compute-heavy — use filters to narrow results.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getProgramAccounts","params":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]}'

Block & Slot

getSlotStandard

Returns the slot that has reached the given or default commitment level.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

getBlockStandard⚡ Heavy[slot]

Returns identity and transaction information about a confirmed block in the ledger. Compute-heavy.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlock","params":[SLOT_NUMBER,{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getLatestBlockhashStandard

Returns the latest blockhash and the last block height at which it is valid.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash","params":[{"commitment":"confirmed"}]}'

getBlockHeightStandard

Returns the current block height of the node.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockHeight","params":[]}'

getBlockTimeStandard[slot]

Get estimated production time of a block, as Unix timestamp.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockTime","params":[SLOT_NUMBER]}'

getBlocksStandard[startSlot, endSlot?]

Get confirmed blocks in a slot range.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlocks","params":[START_SLOT,END_SLOT]}'

getFirstAvailableBlockStandard

Get the slot of the lowest confirmed block that has not been purged from the ledger.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getFirstAvailableBlock","params":[]}'

Transaction

sendTransactionPriority[encodedTransaction]

Submits a signed transaction to the cluster for processing.

Example

curl -X POST https://rpc.fyxvo.com/priority \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["<base64-signed-tx>",{"encoding":"base64","skipPreflight":false}]}'

simulateTransactionPriority[transaction]

Simulate sending a transaction without actually submitting it to the network.

Example

curl -X POST https://rpc.fyxvo.com/priority \
  -H "x-api-key: YOUR_PRIORITY_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"simulateTransaction","params":["<base64-tx>",{"encoding":"base64","sigVerify":false}]}'

getTransactionStandard[signature]

Returns transaction details for a confirmed transaction.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":["SIGNATURE",{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getTransactionsStandard[signatures[]]

Get details for multiple transactions by signature array.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransactions","params":[["SIG1","SIG2"],{"encoding":"json","maxSupportedTransactionVersion":0}]}'

getSignaturesForAddressStandard[address]

Get confirmed signatures for transactions involving an address.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignaturesForAddress","params":["FQ5pyjBQvfadKPPxd66YXksgn8veYnjEw2R1g6aQnFaa",{"limit":10}]}'

getSignatureStatusesStandard[signatures[]]

Returns the statuses of a list of transaction signatures.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignatureStatuses","params":[["SIG1","SIG2"],{"searchTransactionHistory":false}]}'

Network

getHealthStandard

Returns the current health of the node — “ok” if healthy.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

getVersionStandard

Returns the current Solana version running on the node.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getVersion","params":[]}'

getEpochInfoStandard

Returns information about the current epoch including slot index and epoch number.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getEpochInfo","params":[]}'

getEpochScheduleStandard

Get epoch schedule information from the cluster’s genesis config.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getEpochSchedule","params":[]}'

getGenesisHashStandard

Returns the genesis hash of the ledger.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getGenesisHash","params":[]}'

getClusterNodesStandard

Get information about all cluster nodes participating in the network.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getClusterNodes","params":[]}'

getLeaderScheduleStandard

Get the leader schedule for the current or a specific epoch.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLeaderSchedule","params":[]}'

getMinimumBalanceForRentExemptionStandard[dataSize]

Get minimum balance required to make account rent exempt for a given data size.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMinimumBalanceForRentExemption","params":[128]}'

getRecentPerformanceSamplesStandard[limit?]

Get recent performance samples showing transactions and slots per second.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getRecentPerformanceSamples","params":[5]}'

getStakeActivationStandard[pubkey]

Get epoch activation information for a stake account.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getStakeActivation","params":["STAKE_ACCOUNT_PUBKEY"]}'

getVoteAccountsStandard

Get account info and stake for all voting accounts in the current bank.

Example

curl -X POST https://rpc.fyxvo.com/rpc \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getVoteAccounts","params":[]}'

Still have questions?

Docs cover the fastest self-serve path. For launch-fit questions, issue reports, or managed rollout conversations, use the community paths or the contact page.

X Discord Telegram