Defining pricing

Before setting a price, decide what the caller is paying for. A good pay spec makes that unit explicit so agents can compare endpoints and users can approve the cost.

Agent summary

Omit metering for free endpoints.
Use unit: requests and scale: 1 for simple per-call pricing.
Use units like tokens, characters, minutes, pages, or bytes when they match the API cost driver.
Keep price_usd / scale representable by 6-decimal stablecoins.
Use variants when a request field such as model changes the price.

Price basics

Every paid endpoint defines metering. The common shape is:

metering:
  dimensions:
    - direction: usage
      unit: requests
      scale: 1
      tiers:
        - price_usd: 0.01

Field	Description
`direction`	What side of the request is measured: `usage`, `input`, `output`.
`unit`	Metered unit, such as `requests`, `tokens`, or `characters`.
`scale`	Number of units covered by each `price_usd`.
`tiers`	Ordered prices. The first matching tier applies.

Per-request pricing

Use this for search, enrichment, document lookup, and other one-call APIs.

endpoints:
  - method: POST
    path: 'v1/search'
    description: 'Search records by keyword.'
    metering:
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.01

This charges $0.01 per verified request.

Usage-based pricing

Use a larger scale when the natural unit is small.

metering:
  dimensions:
    - direction: usage
      unit: characters
      scale: 1000
      tiers:
        - price_usd: 0.01

This prices text usage at $0.01 per 1,000 characters.

Token pricing

Use separate dimensions when input and output have different costs.

metering:
  dimensions:
    - direction: input
      unit: tokens
      scale: 1000000
      tiers:
        - price_usd: 0.50
    - direction: output
      unit: tokens
      scale: 1000000
      tiers:
        - price_usd: 1.50

This mirrors common AI API pricing: one price for prompt tokens and another for generated tokens.

Volume tiers

Use up_to when the price changes as volume grows.

metering:
  dimensions:
    - direction: usage
      unit: requests
      scale: 1
      tiers:
        - up_to: 1000
          price_usd: 0.01
        - up_to: 10000
          price_usd: 0.005
        - price_usd: 0.002

The final tier omits up_to, so it applies above the previous ceilings.

Variant pricing

Use variants when a request parameter selects different cost paths.

metering:
  variants:
    - param: model
      value: fast
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.01
    - param: model
      value: pro
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.10

Use concrete endpoint descriptions so agents know why one variant costs more than another.

Supported stablecoins use 6 decimal places. If price_usd / scale is below the minimum representable unit, validation will fail or the gateway cannot charge accurately. Increase price_usd or reduce scale.