# Defining pricing

> Price paid endpoints by request, usage unit, variant, or volume tier.

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:

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

## Stablecoin precision

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`.