@polygonlabs/faucet-api-client

Type-safe REST client for the Polygon testnet faucet API, generated with hey-api from the API's committed OpenAPI spec. Every response is validated at runtime with the same Zod schemas the server uses.

Why this package exists

The client is generated from the same schema registry the faucet API serves its routes with (via @polygonlabs/faucet-api-schemas). A change to the API's shape therefore ships as a new package version instead of a silent break. A response that does not match its schema fails at the validation boundary instead of corrupting state further down.

Install

pnpm add @polygonlabs/faucet-api-client

Usage

import { client, getInfo } from '@polygonlabs/faucet-api-client';

client.setConfig({ baseUrl: 'https://faucet-api.polygon.technology' });

const { data } = await getInfo();
// data: { success: true, data: { metadata: { ...networks and tokens } } }

All JSON routes are covered: the core routes (/health-check, /ready, /service-status, /info, /faucetBalances), the auth session routes (/auth/user, /auth/logout) and the transfer routes (/validate, /registerTransferRequest). The session routes need the session cookie, so browsers must send credentials (client.setConfig({ credentials: 'include' })). The OAuth login routes (/auth/github, /auth/twitter) are browser redirects: navigate to them instead of calling them; see MIGRATION.md.

Entry points

• @polygonlabs/faucet-api-client: the fetch-based SDK. It has one function per API operation, the configurable client singleton, and the error-narrowing helpers (isResponseValidationError, isTransportError, isWrapperError).
• @polygonlabs/faucet-api-client/factory: the underlying hey-api client factory, for creating separately configured client instances.