Skip to main content

​
@faremeter/types

@faremeter/types centralizes runtime schemas and TypeScript types used across the Faremeter ecosystem. It is built on top of arktype for expressive runtime validation with precise inferred types.
Source: GitHub › packages/types
Use it whenever you need to:
  • Validate incoming x402 payloads or facilitator requests.
  • Share PaymentHandler/FacilitatorHandler signatures across packages.
  • Guard user input (Solana addresses, EVM addresses, private keys).
  • Compose helpers like generateRequirementsMatcher for quick filtering.

​
Package layout

import * as types from "@faremeter/types";

types.x402;          // Coinbase protocol schemas
types.client;        // client-side handler contracts
types.facilitator;   // facilitator handler contract
types.validation;    // helper guards
types.literal;       // case-insensitive literals
types.solana;        // Solana primitives (Base58 validation)
types.evm;           // EVM primitives (address/private key)
All exports are re-exported from the package root for convenience.

​
x402 module (types.x402)

  • x402PaymentRequirements: schema describing a single accept entry (scheme, network, asset, timeout, metadata, etc.).
  • x402PaymentRequiredResponse: validates the facilitator’s response to /accepts.
  • x402PaymentPayload: encodes the payload inside the X-PAYMENT header.
  • x402PaymentHeaderToPayload: transforms a base64 header string into a validated payload object.
  • x402VerifyRequest / x402VerifyResponse: verification handshake payloads.
  • x402SettleRequest / x402SettleResponse: settlement handshake payloads.
  • x402SupportedKind / x402SupportedResponse: advertise supported payment kinds.
  • generateRequirementsMatcher(schemes, networks, assets): convenience function that returns { matchTuple, isMatchingRequirement }. Useful for filtering facilitator requests by network/scheme/asset in a type-safe manner.
Each schema doubles as a runtime validator (callable like a function) and exposes .infer types for static typing.

​
client module (types.client)

  • RequestContext: minimal info about the triggering HTTP request (request input).
  • PaymentHandler: async function (context, accepts) => PaymentExecer[].
  • PaymentExecer: describes an executable payment attempt with .exec() returning { payload: object }.
  • PaymentExecResult: alias for the payload results.
These contracts underpin @faremeter/fetch and payment handler packages.

​
facilitator module (types.facilitator)

Defines the structure facilitator handlers must implement:
  • getSupported?(): Promise<x402SupportedKind>[]
  • getRequirements(req: x402PaymentRequirements[]): Promise<x402PaymentRequirements[]>
  • handleSettle(requirements, payment): Promise<x402SettleResponse | null>
Returning null from handleSettle signals “not mine” so other handlers in the array can attempt settlement.

​
validation module (types.validation)

  • isValidationError(value): type guard that checks whether an arktype call returned errors.
  • throwValidationError(message, errors): throws a consolidated Error with human-readable messages.
Use these helpers whenever you call an arktype schema to keep error handling consistent across packages.

​
literal module (types.literal)

  • caseInsensitiveLiteral(...values): builds an arktype that accepts any of the given strings, ignoring case. Frequently used with generateRequirementsMatcher.

​
solana module (types.solana)

  • Base58Address: arktype that guards 32–44 byte base58 strings (typical public keys).
  • isBaseAddress(value): predicate wrapping the schema—returns true for valid addresses.

​
evm module (types.evm)

  • Address: validator for 0x-prefixed 40-character hex strings.
  • isAddress(value): predicate.
  • PrivateKey: validator for 64-character hex private keys (with 0x prefix).
  • isPrivateKey(value): predicate.
  • ChainInfo: lightweight description { id, name, rpcUrls } used by wallet helpers.

​
Usage patterns

  • Validate once, trust downstream: Run incoming JSON through the relevant schema. When the schema succeeds, TypeScript narrows the value to the inferred type automatically.
  • Custom matchers: Compose generateRequirementsMatcher with arrays of acceptable schemes/networks/assets to filter requirements without manual string comparisons.
  • API surface documentation: Re-export specific schemas from your service to keep consumers in sync with the same runtime validator.
  • Testing: Combine with isValidationError to assert that malformed payloads are rejected in unit tests.
  • @faremeter/fetch: consumes PaymentHandler / PaymentExecer definitions.
  • @faremeter/facilitator: expects FacilitatorHandler contracts defined here.
  • @faremeter/payment-* & @faremeter/info: build on these schemas to produce network-specific helpers.