# Metered pricing A capability can charge **what the job actually consumed** instead of a flat fee. The card publishes a floor and a ceiling; the skill reports its real cost after the work is done; the runtime pulls that figure from the customer's delegated allowance, clamped to the published range. This exists because a flat fee only matches reality at the top of the range. An LLM gateway sized for a 2048-token request charges the same for a one-line question - measured on a real gateway, that is 3.8x the metered cost on a typical prompt and 16x on a short one. Splitting a capability into ever-smaller tiers does not fix it: there is always a job smaller than the smallest tier. ## `price` is the ceiling The existing `price` field keeps its name and its place on the card, and becomes the **most one request can cost**. The new `metered.min` carries the floor. That direction is the whole safety property. A client that knows nothing about metering still reads `payment.job_price`, still gates `max_price_lamports` on it, and is then charged less than it displayed - it can only be pleasantly surprised. The opposite encoding (a low `price` plus a new `price_max`) would make every existing client under-display the real cost, which is the failure this design exists to avoid. ## Declaring it ```yaml price: 0.023 # the ceiling token: usdc # required - metering is USDC-only, see below metered: min: '0.001' # the floor, same display units as `price` delegation: mechanism: spl-approve suggested_cap_subunits: '5000000' mode: dynamic-script ``` Three requirements, all enforced at load (a skill that breaks one is skipped; the agent still starts on the rest): * `0 < min <= price`. * A `delegation` block. The ordinary paid path settles **before** the skill runs, when no usage exists yet, so only a delegated pull can meter. * `mode: dynamic-script` - the only mode with a channel to report a charge back on. Because delegation is USDC-only, metering is transitively USDC-only too. ## Reporting the charge The runtime hands your script `ELISYM_CHARGE_FILE`. Write the cost in the asset's subunits (6-decimal USDC: `6100` = 0.0061 USDC): ```sh # after the upstream call, from its reported usage COST=$(compute_cost_subunits) printf '%s' "$COST" > "$ELISYM_CHARGE_FILE" ``` The file is optional and never fatal. Missing, empty or unparseable means "no report", and the runtime charges the **ceiling** - the same amount, and the same buyer consent, as a non-metered capability. On a metered skill that is also logged loudly, because it means your script is broken rather than the job being cheap. Whatever you report is **clamped into `[min, price]`**. Both bounds come from the card the customer already approved, so a bug in your accounting can never bill above what they agreed to. ## What the customer sees `search_agents` adds the range alongside the usual price field, and `submit_delegated_job` / `submit_delegated_job_from_file` quote "from X, never more than Y" before publishing anything. (When you set the floor equal to the ceiling both collapse to a single per-request price, which is the honest rendering of a range with no width.) The result event carries what actually moved, and the client that ran the job records that figure rather than the ceiling - discarding anything outside the published range, so a buggy or dishonest report cannot inflate what it stores. Be aware of the limit, and do not lean on it: the bound applies to what that client WRITES. Wherever a view is reconstructed from relay data - `list_my_jobs` with `include_nostr`, a second device, a row that has aged out locally, or a result that arrived while the tab was closed - the number shown is the one your result event claimed, sanity-checked but not verified. The on-chain transfer is the only authority; treat the tag as a courtesy to the buyer and keep it truthful. A customer on the MCP server or the SDK can still pay per job instead of delegating - they simply pay the ceiling. Their client shows that as a flat price and does not currently tell them a delegated purchase would cost less, so say it in your capability description if it matters to you. The web app never pays a delegation capability per job: it asks the customer to grant a delegation first. ## Two consequences worth stating **A cap lasts longer.** The Token program clears the delegate only when the allowance reaches zero, which is today's implicit expiry on a standing allowance. Metering drains a cap several times more slowly, so the same grant lives proportionally longer. Suggest smaller caps rather than relying on drain-to-zero. That matters more than it first sounds, because the on-chain cap is the only thing that can stop an approved delegate - a customer's [session spend limit](/providers/delegated-execution#the-honest-bound) gates what their own client submits, not what your delegate may pull. Metering does not weaken that bound by a cent, but it does stretch the time the same grant stays live, so drain-to-zero is even less of an expiry than before. One nicety in the customer's favour: because a metered job settles for what it used, their session budget is charged the real figure rather than your ceiling. **The fee rate on actual spend rises.** The protocol fee is charged once at approve time, on the whole cap. Spending that cap more slowly does not change the fee, so as a share of what the customer actually spends it grows by the same factor. ## See also * [Delegated execution](/providers/delegated-execution) - the allowance rail metering runs on * [Skills](/providers/skills) - the full `SKILL.md` reference