# `X402.Telemetry`
[🔗](https://github.com/cardotrejos/x402/blob/v0.9.0/lib/x402/telemetry.ex#L1)

Telemetry event definitions and emission helpers for x402 operations.

All events emitted by this library use the `[:x402, module, operation]` format
and include `%{count: 1}` as measurements.

Emitted events:

- `[:x402, :payment_required, :encode]`
- `[:x402, :payment_required, :decode]`
- `[:x402, :payment_signature, :decode]`
- `[:x402, :payment_signature, :validate]`
- `[:x402, :payment_signature, :decode_and_validate]`
- `[:x402, :payment_response, :encode]`
- `[:x402, :payment_response, :decode]`
- `[:x402, :extension_responses, :decode]`
- `[:x402, :payment_identifier, :legacy]` — a deprecated `paymentIdentifier`
  format id was received (metadata `:source` is `:gate` or `:mcp`)
- `[:x402, :siwx, :legacy]` — a deprecated `{message, signature}`
  `SIGN-IN-WITH-X` header was received (metadata `:source` is `:gate`)
- `[:x402, :client, :select]`
- `[:x402, :client, :sign]`
- `[:x402, :client, :build]`
- `[:x402, :client, :request]`
- `[:x402, :client, :siwx]` — a payer client answered a Sign-In-With-X
  challenge (metadata `:transport`, `:chain_id`, and `:outcome` —
  `:authenticated` or `:payment_required` — or `:reason` on error).
  `:chain_id` is the selected signing chain, never `:auto`, and is `nil`
  on errors before chain selection. Direct `X402.Client.SIWX` calls
  default `:transport` to `nil`; HTTP/MCP drivers always identify it.
- `[:x402, :rpc, :request]`
- `[:x402, :verify, :evm]`
- `[:x402, :verify, :svm]`
- `[:x402, :facilitator_engine, :verify]`
- `[:x402, :facilitator_engine, :settle]`

Metadata always includes `:status` (`:ok` or `:error`) and may include
additional operation-specific fields such as `:reason`, `:header`, or
`:fields`.

Other modules emit events outside this helper — the payment gate
(`[:x402, :plug, ...]`), the MCP transport (`[:x402, :mcp, ...]`), and
the facilitator client (`:telemetry.span/3` events under
`[:x402, :facilitator, operation]` plus `[:x402, :facilitator, :failover]`).
`events/0` lists every event name the library can emit, and
`X402.Telemetry.Metrics` / `X402.Telemetry.Stats` build on that list.

# `event`

```elixir
@type event() :: [atom(), ...]
```

A telemetry event name emitted by this library.

# `module_name`

```elixir
@type module_name() ::
  :payment_required
  | :payment_signature
  | :payment_response
  | :extension_responses
  | :payment_identifier
  | :siwx
  | :client
  | :rpc
  | :verify
  | :facilitator_engine
```

# `operation`

```elixir
@type operation() ::
  :encode
  | :decode
  | :validate
  | :decode_and_validate
  | :select
  | :sign
  | :build
  | :request
  | :evm
  | :svm
  | :verify
  | :settle
  | :legacy
  | :siwx
```

# `status`

```elixir
@type status() :: :ok | :error
```

# `emit`
*since 0.1.0* 

```elixir
@spec emit(module_name(), operation(), status(), map()) :: :ok
```

Emits an x402 telemetry event.

## Examples

    iex> X402.Telemetry.emit(:payment_required, :encode, :ok, %{header: "PAYMENT-REQUIRED"})
    :ok

# `event_name`
*since 0.1.0* 

```elixir
@spec event_name(module_name(), operation()) :: [atom()]
```

Returns the telemetry event name for a module and operation.

## Examples

    iex> X402.Telemetry.event_name(:payment_required, :encode)
    [:x402, :payment_required, :encode]

# `events`
*since 0.9.0* 

```elixir
@spec events() :: [event()]
```

Returns every telemetry event name this library can emit.

Span operations (`X402.Facilitator` verify, settle, supported, discovery)
are listed as their `:start`, `:stop`, and `:exception` events.

## Examples

    iex> [:x402, :plug, :rate_limited] in X402.Telemetry.events()
    true

    iex> [:x402, :facilitator, :settle, :stop] in X402.Telemetry.events()
    true

# `facilitator_operations`
*since 0.9.0* 

```elixir
@spec facilitator_operations() :: [atom()]
```

Returns the facilitator client operations instrumented with `:telemetry.span/3`.

## Examples

    iex> X402.Telemetry.facilitator_operations()
    [:verify, :settle, :supported, :list_resources, :search_resources]

---

*Consult [api-reference.md](api-reference.md) for complete listing*