Method.evm.charge

Creates an EVM charge payment method for native MPP and inline x402 exact payment flows.

Usage

import { Mppx, evm } from 'mppx/server'
 
const mppx = Mppx.create({
  methods: [
    evm.charge({
      currency: evm.assets.baseSepolia.USDC,
      recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
      x402: {
        facilitator: 'https://x402.org/facilitator',
      },
    }),
  ],
  secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret',
})
 
export async function handler(request: Request) {
  const response = await mppx.evm.charge({
    amount: '0.01',
    description: 'Premium API access',
  })(request)
 
  if (response.status === 402) return response.challenge
  return response.withReceipt(Response.json({ data: '...' }))
}

Use x402.facilitator to run x402 exact settlement inline with the MPP route. The method verifies signatures and payment terms, calls the facilitator's non-mutating verification during validation, then revalidates before settlement.

Use settle when you want to settle Credentials yourself. Custom settlers remain responsible for chain-state checks and replay protection because standalone validation doesn't call the mutating settlement callback.

Use lowercase evm.assets and evm.chains for known asset and chain metadata. Uppercase aliases remain available for compatibility, but new code should use the lowercase namespaces.

Return type

Returns a function that accepts a Request and returns a response object with payment status.

type ReturnType = (request: Request) => Promise<
  | { status: 402; challenge: Response }
  | { status: 200; withReceipt: <T>(response: T) => T }
>

Configuration

These parameters configure the evm.charge() constructor.

authorization (optional)

• Type: { name: string; version: string }

EIP-3009 token domain metadata. Required for custom currency addresses and inferred for known assets.

canOffer (optional)

• Type: Method.CanOfferFn

Returns whether this configured EVM offer is available when an HTTP handler composes multiple offers. The hook receives the normalized, immutable payment request and a clone of the incoming Request.

chainId (optional)

• Type: number

EVM chain ID. Required for custom currency addresses and inferred for known assets.

currency

• Type: Address | KnownAsset

Token contract address or known EVM asset metadata.

import { evm } from 'mppx/server'
 
const method = evm.charge({
  currency: evm.assets.baseSepolia.USDC, 
  recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  x402: {
    facilitator: 'https://x402.org/facilitator',
  },
})

decimals (optional)

• Type: number

Token decimal places. Required for custom currency addresses and inferred for known assets.

onPaymentSuccess (optional)

• Type: Method.OnPaymentSuccessFn<typeof evm.Methods.charge>

Runs after this EVM charge succeeds. The hook receives the optional associated Challenge, canonical request, its Receipt, the HTTP input when available, and the resolved pre-transform requestInput when route options are available. Errors don't change payment handling.

recipient

• Type: Address

Wallet address that receives the payment.

settle (optional)

• Type: (parameters: SettleAuthorizationParameters) => Promise<{ reference: string; timestamp?: string }>

Custom settlement callback. Use this instead of x402.facilitator when you settle EIP-3009 authorization Credentials yourself.

The callback runs only during broadcast. validateCredential() still verifies the signature, Challenge binding, payment terms, validity window, and declared source without calling settle.

x402 (optional)

• Type: { facilitator?: string | Facilitator; fetch?: typeof globalThis.fetch; maxTimeoutSeconds?: number; routeBinding?: 'required' | 'resource' }

x402 compatibility options. Pass facilitator to verify and settle x402 exact payments inline. fetch configures facilitator requests, and maxTimeoutSeconds defaults to 300.

routeBinding controls scoped-route interoperability:

• 'resource' (default)—Accept standard x402 Credentials by comparing the echoed resource URL and payment requirements. Credentials with the mppx extension retain full route-bound nonce verification.
• 'required'—Require every x402 Credential for a scoped route to include the mppx extension and route-bound nonce. Use this when scope, opaque values, or metadata must be cryptographically bound.

Both modes verify any Challenge body digest against the request. Standard x402 Credentials can pay Proxy routes under the default mode because the proxy's derived scope no longer requires the optional extension.

Request parameters

amount

• Type: string

Payment amount in display units.

description (optional)

• Type: string

Human-readable description of the payment request.

externalId (optional)

• Type: string

External correlation ID for the payment request.