Protocol fee

​

The numbers

​

Math worked example

amount      = 12_345        atoms (= 0.012345 USDC, what the seller quoted)
bps         = 100           (1.00%)
fee         = ceil(12_345 * 100 / 10_000)
            = ceil(123.45)
            = 124           atoms (= 0.000124 USDC)
gross       = amount + fee
            = 12_469        atoms (= 0.012469 USDC, what the buyer signs)

{
  "kind": "earn",
  "price": {
    "amount": "12345",
    "currency": "USDC",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "fee": "124",
    "gross": "12469",
    "feeBps": 100,
    "feeAuthority": "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W"
  },
  "tx_sig": "..."
}

​

Wire shape — extra['leash.fee']

{
  "scheme": "exact",
  "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
  "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
  "payTo": "<seller payTo ATA>",
  "amount": "12345",
  "extra": {
    "leash.fee": {
      "v": "1",
      "bps": 100,
      "feeAuthority": "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W",
    },
  },
}

​

Verifying the live rate

$ curl -sS https://api.leash.market/v1/health | jq .protocol_fee
{
  "bps": 100,
  "pct": "1.00%",
  "authorities": {
    "solana-mainnet": "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W",
    "solana-devnet":  "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W"
  }
}

$ curl -sS https://devnet-facilitator.leash.market/health | jq .protocol_fee
{ "bps": 100, "enforcement": "enforce", "authority": "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W" }

​

Budgeting allowances and treasuries

• SPL Approve (executive allowance). A 5 USDC Approve only buys ~4.95 USDC of seller-quoted endpoints — the last fee leg pushes you over the cap and the settlement fails with insufficient_allowance. Either gross-up yourself with applyFeeGrossUp from @leash/core, or pass pad_for_protocol_fee: true on POST /v1/agents/{mint}/delegation/prepare — the response echoes fee_padding_atoms so you can audit.
• Treasury balance. Same reasoning at the SPL balance level. Top up 5.05 USDC (atoms 5_050_000) if you want to comfortably consume 5 USDC of seller-quoted endpoints. The web playground’s “Provision stable ATAs” + “Set allowance” buttons both do the gross-up automatically.

import { applyFeeGrossUp, resolveLeashFeeBps } from '@leash/core';

const sellerNetAtoms = 5_000_000n; // 5 USDC
const { fee, gross } = applyFeeGrossUp(sellerNetAtoms, resolveLeashFeeBps());
// fee   = 50_000n   (0.05 USDC)
// gross = 5_050_000n (5.05 USDC) — use this to size SPL Approve / fund treasury

​

What the facilitator does

1. Walk past leading CreateAssociatedTokenAccountIdempotent instructions (up to two — one for the seller’s payTo ATA, one for the fee vault ATA). Each is validated: payer must be the facilitator’s fee-payer, mint and token program must match the transfer leg, and each target ATA must be either the seller’s payTo or the fee authority’s ATA for the same mint. Unknown ATA creates are rejected.
2. Identify the seller TransferChecked immediately after any ATA creates. Confirm it debits the buyer’s source ATA and credits the seller’s payTo ATA for the advertised amount on the advertised mint.
3. If extra['leash.fee'] is present, confirm a second TransferChecked follows: same source ATA, same mint, targets the feeAuthority’s ATA, exact feeAtomic as derived from amount × bps.
4. Reject (enforce), warn (warn), or ignore (off) per LEASH_FEE_ENFORCE. The hosted facilitators run enforce; warn is for staged rollouts.
5. Simulate the fully co-signed transaction against the RPC to catch balance / blockhash problems before broadcast.

​

What the indexer does

• Receipt-side. Whenever a settled earn receipt with price.fee is ingested via POST /v1/receipts/{agent}, /x/{id} (paywall), or the receipt-pull worker, emitProtocolFeeEvent fires once, idempotent on (network, receipt_hash).
• On-chain fallback. When the indexer sees a positive tokenBalanceDeltas to the fee authority on a watched ATA, it emits the same event with metadata.source = 'on_chain'. This catches the rare case of a fee landing without a receipt (e.g. a buyer that never POSTed the spend receipt).

​

Self-hosting @leash/facilitator with your own fee

​

SDK reference

import {
  applyFeeGrossUp,
  buildLeashFeeExtra,
  computeFeeAtoms,
  computeLeashFeeForRequirements,
  parseLeashFeeExtra,
  resolveLeashFeeAuthority,
  resolveLeashFeeBps,
  type LeashFeeExtra,
  type ResolvedLeashFee,
} from '@leash/core';

• resolveLeashFeeBps() — current fee rate (env-overridable).
• resolveLeashFeeAuthority(network) — fee owner pubkey for 'mainnet' | 'devnet'.
• computeFeeAtoms(amount, bps) — pure, ceiling-rounded.
• applyFeeGrossUp(amount, bps?) — returns { fee, gross }.
• buildLeashFeeExtra({ network, bps?, authority? }) — synchronous, returns the wire shape sellers stamp on extra['leash.fee'].
• parseLeashFeeExtra(extra) — parses the wire shape, returns null on absence/malformation.
• computeLeashFeeForRequirements({ network, asset, tokenProgram, amount, extra }) — async, derives (bps, feeAtomic, grossAtomic, feeDestination) for a specific paymentRequirements entry. Used by both buyer scheme and facilitator verifier.

​

See also

• Run a facilitator — boot your own and configure the fee env.
• Monetise an API — where the fee fits in the end-to-end seller flow.
• Explorer tracking — how protocol.fee.collected events surface in the UI.
• Receipt format — the canonical price.fee / price.gross / price.feeBps / price.feeAuthority fields on every ReceiptV1.