> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Handlers

> The plugin interface that connects wallets to payment schemes.

A payment handler is the bridge between a wallet and a payment scheme. When the fetch wrapper receives a 402 response, it passes the payment requirements to each registered handler. Handlers that can fulfill a requirement return a `PaymentExecer` -- an object that can execute the payment when called.

## The `PaymentHandler` interface

```typescript theme={null}
import type { RequestContext, PaymentExecer } from "@faremeter/types/client"
import type { x402PaymentRequirements } from "@faremeter/types/x402v2"

type PaymentHandler = (
  context: RequestContext,
  accepts: x402PaymentRequirements[]
) => Promise<PaymentExecer[]>
```

A handler receives the request context and a list of payment requirements. It returns an array of `PaymentExecer` objects for every requirement it can fulfill. If the handler cannot fulfill any requirement, it returns an empty array.

## The `PaymentExecer` interface

```typescript theme={null}
type PaymentExecer = {
  requirements: x402PaymentRequirements
  exec(): Promise<PaymentExecResult>
}
```

Each execer is bound to a specific requirement. When `exec()` is called, it signs the payment using the associated wallet and returns the payload for the `X-PAYMENT` header.

## How handlers compose

Multiple handlers can be registered simultaneously. The fetch wrapper collects all execers from all handlers and passes them to a payer chooser function.

```typescript theme={null}
import { wrap, chooseFirstAvailable } from "@faremeter/fetch"

const fetchWithPayment = wrap(fetch, {
  handlers: [solanaHandler, evmHandler],
  payerChooser: chooseFirstAvailable,
})
```

The default payer chooser, `chooseFirstAvailable`, picks the first handler that can fulfill a requirement. You can provide a custom chooser to implement logic like balance checking, fee comparison, or chain preference.

## Handler selection flow

```
402 response received
    |
    v
For each registered handler:
    |--- Handler receives requirements
    |--- Handler checks scheme/network/asset against its wallet
    |--- Returns PaymentExecer[] for matches, [] for no match
    |
    v
All execers collected
    |
    v
payerChooser selects one execer
    |
    v
execer.exec() signs the payment
    |
    v
Payment attached to retry request
```

## Built-in handlers

| Package                           | Handler                | Schemes       |
| --------------------------------- | ---------------------- | ------------- |
| `@faremeter/payment-solana/exact` | `createPaymentHandler` | SPL tokens    |
| `@faremeter/payment-evm/exact`    | `createPaymentHandler` | EIP-3009 USDC |

## Building custom handlers

A custom handler follows the same interface. Return `PaymentExecer` objects for requirements you can handle, and an empty array for those you cannot.

```typescript theme={null}
import type { PaymentHandler, PaymentExecer } from "@faremeter/types/client"

const createCustomHandler = (wallet: CustomWallet): PaymentHandler => {
  return async (context, accepts) => {
    const execers: PaymentExecer[] = []

    for (const req of accepts) {
      if (req.scheme === "my-scheme" && req.network === "my-network") {
        execers.push({
          requirements: req,
          exec: async () => {
            const signature = await wallet.sign(req)
            return { payload: { signature } }
          },
        })
      }
    }

    return execers
  }
}
```

See [Plugins](/plugins) for community-contributed handlers.

## Further reading

* [Fetch Wrapper](/client/fetch-wrapper) -- How to register handlers with the fetch wrapper.
* [Payment Schemes](/concepts/payment-schemes) -- The schemes that handlers implement.