Falcon Cloud RPC gateway

Authentication

Every RPC call needs an API key. Send it as Authorization: Bearer fplk_… or X-API-Key: fplk_….

Keys are shown once when issued and stored only as a SHA-256 hash. Keep them server-side; never ship a key in browser code or a public repo. Every plan, including Free, needs a key. Keys are issued on request through BEARTEC: see get an API key.

Endpoints

Browser calls (CORS)

Browser requests are accepted only from approved origins: https://falcon-fpl.comhttps://www.beartec.uk. Call the gateway from your own server for anything else.

Not supported yet

• Batch requests (a JSON array) return HTTP 400. Send one request per call.
• There is no WebSocket or subscription endpoint. Poll instead.

Both are planned for a later release.

Allowed methods

Read methods plus transaction submit. Node admin and operator calls are never exposed.

curl

curl -s https://rpc.falcon-fpl.com/v1/rpc \
  -H "Authorization: Bearer $FPL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"fpl_getAccount","params":{"account":"alice"}}'

JavaScript

// Node 18+ / browsers. Keep the key server-side.
async function fpl(method, params = {}, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const r = await fetch('https://rpc.falcon-fpl.com/v1/rpc', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.FPL_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
    })
    if (r.status === 429) {
      const wait = Number(r.headers.get('retry-after') ?? 1)
      await new Promise((ok) => setTimeout(ok, wait * 1000))
      continue
    }
    const body = await r.json()
    if (body.error) throw new Error(`${body.error.code}: ${body.error.message}`)
    return body.result
  }
  throw new Error('rate limited')
}

const status = await fpl('fpl_status')

Python

import os, time, requests

def fpl(method, params=None, tries=4):
    for _ in range(tries):
        r = requests.post(
            "https://rpc.falcon-fpl.com/v1/rpc",
            headers={"Authorization": f"Bearer {os.environ['FPL_API_KEY']}"},
            json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}},
            timeout=10,
        )
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        body = r.json()
        if "error" in body:
            raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
        return body["result"]
    raise RuntimeError("rate limited")

print(fpl("fpl_orderBook", {"pair": "BTC4-FPL", "levels": 10}))

Errors

Errors use the JSON-RPC envelope { "error": { "code", "message" } }.

Handling 429

Each key has a per-second rate with a short burst allowance, a separate per-minute limit for fpl_submitTx, and a monthly quota in units. When you exceed a rate, the gateway answers HTTP 429 with a Retry-After header in seconds: wait that long, then retry. The examples above do this. A quota 429 has no Retry-After and lasts until the 1st of the month (00:00 UTC). Check GET /v1/usage to see where you are. Limits per plan: pricing.