API reference

Two hosts, two different APIs

The apex feerelayer.net is the service website. A subdomain <name>.feerelayer.net is a relay. Which routes exist depends entirely on which of the two you are talking to.

Anything else is a 404. In particular /info and /relay on the apex are not relay routes, and /create on a subdomain is not a create route.

The fee model

A relay declares a percent rate (hard cap 2%) and a minimum floor in USDC (between 0.002 and 0.10). All money math happens in raw USDC units: integers, six decimals, so 1.00 USDC is 1000000.

feeRaw = max( round(amountRaw * rate), minRaw )

There is no rounding up to the cent: a sub-cent floor is honored exactly as declared. The client derives this same number before it signs, and the relay re-derives it server side. If the two disagree, the relay rejects.

The split across recipients

The total fee is then split across one or two declared recipients. With one recipient it all goes there. With two, from src/fee-split.js:

cut0 = min( fee, max( minRaw0, floor(fee * bps0 / 10000) ) )
cut1 = fee - cut0

Recipient 0 is always the relay and gas payer. Recipient 1, when declared, is the operator. bps0 is recipient 0's share in basis points, taken from the relay record as-is. minRaw0 is that recipient's own floor: the record states it as min_usdc in USDC, and the worker converts it to raw units before this line runs, so a declared min_usdc of 0.01 enters the formula as 10000. Convert it yourself before you compare, or your cut0 will not match the relay's.

amountRaw = 500000
fee   = max( round(500000 * 0.01), 10000 ) = max(5000, 10000) = 10000   // 0.01 USDC
cut0  = min( 10000, max( 10000, floor(10000 * 3000 / 10000) ) )
      = min( 10000, max( 10000, 3000 ) ) = 10000
cut1  = 10000 - 10000 = 0                                              // operator gets nothing

Where the payee is also a fee recipient

Paying the relay operator through their own relay is legitimate and does work. The payment and the fee then land on the same account, so the validator cannot classify transfers by destination alone. It falls back to transaction order (the builder always emits the recipient transfer first), and in that fallback it charges the fee on the largest transfer present, so the ambiguity always resolves in the relay's favour rather than the caller's.

GET /info

On a relay subdomain. Machine discovery: the wallet reads this before it builds anything, to learn who co-signs and what the fee will be. No authentication, open CORS, no-store.

curl -s https://free.feerelayer.net/info

200, application/json:

{
  "version": 2,
  "name": "free",
  "wallet": "yffkypTLRypQ7AJJM1dqZfNKQGvye9ifedBc3dxaCJo",
  "fees": {
    "memo": 0,
    "payment": {
      "type": "percent",
      "rate": 0.01,
      "min": 0.01,
      "recipients": [
        { "ata": "<base58 token account>", "bps": 3000, "min_usdc": 0.01 },
        { "ata": "<base58 token account>", "bps": 7000 }
      ]
    }
  },
  "free_cancellation": false,
  "supported_actions": ["memo", "payment"],
  "turnstile_sitekey": "0x4AAAAAAA..."
}

POST /relay

On a relay subdomain. You build and sign your own transaction; the relay adds the fee-payer signature so the SOL gas is covered. By default it then submits the transaction for you; with "mode": "sign" it only returns its signature and you broadcast the co-signed transaction yourself. It never takes custody of anything.

Request

POST https://<name>.feerelayer.net/relay
Content-Type: application/json
X-Turnstile-Token: <token>        // FREE flows only, see below

{
  "tx": "<base64 of the serialized, partially signed transaction>",
  "type": "payment",                // or "memo"
  "mode": "sign"                    // optional, see below
}

Response

200, application/json, with the relay name echoed in a header:

x-relay-mode: free

{ "signature": "5zKZ3uRd..." }

With "mode": "sign" the body also says so, and the signature is the relay's slot-0 signature, which is by construction the transaction id once you broadcast it:

{ "signature": "5zKZ3uRd...", "mode": "sign" }

If you asked for "mode": "sign" and the answer has no mode, you are talking to a relay that predates the option: it has already submitted the transaction, do not broadcast it again.

Every failure is { "error": "<string>" } at the status below. Open CORS on both.

Every error POST /relay can return

These are the literal strings, in the error field. Values in angle brackets are interpolated by the worker.

Worked examples

Discover the policy:

curl -s https://free.feerelayer.net/info

Dry run a payment, which signs nothing:

curl -s -X POST https://free.feerelayer.net/simulate \
  -H 'Content-Type: application/json' \
  -d '{"tx":"AQAAAAAA...","type":"payment"}'

Submit a payment. No captcha header: paid flows do not carry one.

curl -s -i -X POST https://free.feerelayer.net/relay \
  -H 'Content-Type: application/json' \
  -d '{"tx":"AQAAAAAA...","type":"payment"}'

Submit a free memo. This one does need the captcha token:

curl -s -X POST https://free.feerelayer.net/relay \
  -H 'Content-Type: application/json' \
  -H 'X-Turnstile-Token: 0.abc123...' \
  -d '{"tx":"AQAAAAAA...","type":"memo"}'

List every relay, or fetch this reference as OpenAPI:

curl -s https://feerelayer.net/relays.json
curl -s https://feerelayer.net/openapi.json

POST /simulate

On a relay subdomain. The dry run of POST /relay: same body, same relay resolution, same parse, same co-sign safety guard, same validators, same reason strings. Then it stops and reports instead of signing.

It never signs and never submits. No signature is produced, nothing reaches the Solana network, no quota is consumed and nothing is written anywhere. It does not even need the signing key or an RPC URL to answer. Use it while you are still getting the fee split right, so the loop is "fix the transaction" rather than "spend one to read an error string".

curl -s -X POST https://free.feerelayer.net/simulate \
  -H 'Content-Type: application/json' \
  -d '{"tx":"<base64>","type":"payment"}'

Always 200, always the same shape

A refusal is still an HTTP 200: the report was produced, and the verdict is in the body. Read ok. status is the status POST /relay would have returned, and reason is the same string it would have returned, so the whole error table above applies here too. Every field below is always present.

{
  "ok": false,
  "reason": "Insufficient payment fee (our cut): got 3000, need 10000",
  "status": 400,
  "relay": "free",
  "type": "payment",
  "feeRequiredRaw": 10000,
  "feeRequiredUsdc": 0.01,
  "feePaidRaw": 3000,
  "feePaidUsdc": 0.003,
  "cuts": [
    { "index": 0, "ata": "<base58>", "bps": 3000, "minUsdc": 0.01,
      "requiredRaw": 10000, "requiredUsdc": 0.01,
      "paidRaw": 3000, "paidUsdc": 0.003, "present": true, "covered": false },
    { "index": 1, "ata": "<base58>", "bps": 7000, "minUsdc": null,
      "requiredRaw": 0, "requiredUsdc": 0,
      "paidRaw": 0, "paidUsdc": 0, "present": false, "covered": true }
  ],
  "recipient": "<base58 destination token account>",
  "amountRaw": 500000,
  "amountUsdc": 0.5,
  "wouldCosign": false,
  "simulated": true,
  "notes": []
}

POST /create, or: run your own relay

On the apex only. Self-service, no account, no KYC. You submit a name and the Solana wallet you want paid; the relay is live at <name>.feerelayer.net the moment it returns.

curl -s -X POST https://feerelayer.net/create \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "bobpay",
    "payout_wallet": "<your base58 Solana wallet>",
    "rpc": "helius",
    "rate": 0.015,
    "min": 0.01,
    "turnstileToken": "<token from the homepage widget>"
  }'

200:

{
  "name": "bobpay",
  "endpoint": "https://bobpay.feerelayer.net",
  "share_link": "https://bobpay.feerelayer.net/manual"
}

No relay record is written on any rejection: the store write is the last step, after every check has passed.

How your fee is shared

On a hosted relay with a non-zero rate, the record is created with two recipients: 3000 bps to the infrastructure with a 0.01 USDC floor, 7000 bps to you. That policy lives in /create only, written into your record as plain data. Everything downstream just honors whatever recipients a record declares. A relay with rate: 0, or one whose payout account is the infrastructure account itself, is created with a single recipient instead. Re-read the fee model above before you plan on that 70%: below roughly a 1.00 USDC payment, your cut is zero.

Integration snippet

Pick a relay and copy the client code for it. Everything below is generated in your browser from the list above, nothing is sent anywhere.

What this relay refuses to co-sign, and why

The relay checks that account slot 0 is its own wallet, and then it signs the whole message. That one signature authorizes every instruction in the transaction that touches the relay's key. So the interesting question is not what the relay signs, it is what it refuses to sign. Three rules, enforced before any signature exists, on payments and memos alike.

1. Only three programs are allowed to appear

SPL Memo, SPL Token, and Associated Token. That is the entire allowlist. The wallet's builders emit only those three, so nothing legitimate is lost, and the refusal kills two whole classes of abuse at once: a System Program transfer with the relay at slot 0 would drain its SOL gas outright, and a Compute Budget instruction would let a caller burn the relay's priority-fee budget for free. Any exotic cross-program call is refused for the same reason.

if (!allowed.some((a) => arraysEqual(a, progBytes))) {
  return { valid: false, reason: 'cosign_refused: disallowed program in a relay-cosigned transaction' };
}

2. The relay's own fee account may never be slot 0 of a token instruction

For Transfer, TransferChecked, Approve, Burn, CloseAccount and SetAuthority alike, the first account of an SPL Token instruction is the account being acted upon: the victim slot. If the relay's fee account sat there, the relay would be moving its own USDC under its own signature, and the fee validation would not notice because a small honest fee elsewhere in the transaction is enough to satisfy it. So the fee account is allowed to appear in exactly one role, as a transfer destination, and nowhere else.

const acct0 = idxs[0] != null ? parsed.accountKeys[idxs[0]] : null;
if (acct0 && arraysEqual(acct0, ourAtaBytes)) {
  return { valid: false, reason: 'cosign_refused: relay fee ATA used as a transfer source/authority' };
}

The check is deliberately discriminator-agnostic. It does not ask which token instruction this is, which is why it also covers instructions nobody has thought of yet.

3. The relay's own pubkey may not appear inside a token instruction at all

In a legitimate payment the relay is the transaction-level fee payer and, at most, the funder of a new recipient account through the Associated Token program. It is never an account inside a token instruction. Its presence there would mean it is the authority moving a token account it owns, on any mint, not just USDC. Refused: cosign_refused: relay pubkey used as a Token-instruction authority.

And one more, on the free path

A memo transaction has no legitimate reason to create an associated token account, so any Associated Token instruction in a memo transaction is refused with memo_tx_must_not_create_ata. Without that rule, a free memo could quietly make the relay pay account rent, once per transaction, forever. It is griefing rather than theft, and it is bounded by the captcha and the quotas, but there is no reason to accept it.

What the relay does not check

It does not know or care who you are paying, or why. It never holds your funds, it never sees a private key of yours, and it cannot alter the destination or the amount you signed. If your transaction is well formed, pays the declared fee, and touches none of the relay's own accounts as a source, it gets co-signed.