FALCONQ

Authentication

FalconQ uses per-customer API keys to authenticate every request. Each product type has its own key prefix. Include your key in every request to access the Solana network.

API Key Types

ProductKey PrefixUsed For
FalconQ RPCfq_rpc_live_...HTTP RPC + WebSocket + REST
FalconQ gRPCfq_grpc_live_...Yellowstone gRPC streaming
FalconStreamfq_fs_live_...Shred-stage gRPC (RabbitStream)

Create and manage your API keys in the dashboard. Keys are shown once at creation and never stored in plain text.

HTTP RPC: Bearer Header

The recommended method. Pass your key in the Authorization header.

curl -X POST https://api.falconq.xyz/v1/rpc \
  -H "Authorization: Bearer fq_rpc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBalance",
    "params": ["vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"]
  }'

HTTP RPC: Query Parameter

Alternatively, pass your key as the api-key query parameter. Useful for quick testing.

curl -X POST "https://api.falconq.xyz/v1/rpc?api-key=fq_rpc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBalance",
    "params": ["vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"]
  }'

Using with @solana/web3.js

Pass your API key via custom HTTP headers when creating a Connection instance.

import { Connection, PublicKey } from '@solana/web3.js'

const connection = new Connection(
  'https://api.falconq.xyz/v1/rpc',
  {
    httpHeaders: {
      Authorization: 'Bearer fq_rpc_live_YOUR_KEY',
    },
    commitment: 'confirmed',
  }
)

const balance = await connection.getBalance(
  new PublicKey('vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg')
)
console.log('Balance (lamports):', balance)

WebSocket

Pass your key in the connection URL query string. Authentication is validated on the upgrade request before the connection is established.

const WebSocket = require('ws')

const ws = new WebSocket(
  'wss://api.falconq.xyz/v1/ws?api-key=fq_rpc_live_YOUR_KEY'
)

ws.on('open', () => {
  console.log('Connected to FalconQ WebSocket')

  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'accountSubscribe',
    params: [
      'vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg',
      { encoding: 'jsonParsed', commitment: 'confirmed' }
    ]
  }))
})

ws.on('message', (data) => {
  const response = JSON.parse(data.toString())
  console.log('Update:', response)
})

ws.on('error', (err) => {
  console.error('WebSocket error:', err.message)
})

REST: x-api-key Header

REST endpoints accept the Shyft-compatible x-api-key header (a Bearer header or api-key query parameter also works). Use your RPC key.

curl "https://api.falconq.xyz/sol/v1/wallet/balance?network=mainnet-beta&wallet=YOUR_WALLET" \
  -H "x-api-key: fq_rpc_live_YOUR_KEY"

gRPC (Yellowstone Metadata)

Pass your gRPC key in the x-token metadata field. This is required for every gRPC stream.

const grpc = require('@grpc/grpc-js')

const metadata = new grpc.Metadata()
metadata.set('x-token', 'fq_grpc_live_YOUR_KEY')

const stream = client.Subscribe(request, metadata)

stream.on('data', (update) => {
  console.log('gRPC update:', update)
})

stream.on('error', (err) => {
  console.error('gRPC error:', err)
})

Security Best Practices

1.

Never expose API keys in client-side code. Always proxy requests through your backend server.

2.

Use environment variables. Store keys in .env files, never hardcode them.

3.

Rotate keys regularly. Create new keys and revoke old ones from the dashboard.

4.

Use separate keys per environment. Keep production and development keys isolated.

5.

Prefer Bearer header auth. Query parameters may appear in server logs and browser history.