SDKs

Two official clients over the same HTTP API — PHP from Packagist, JavaScript and TypeScript from npm — plus a Laravel integration built on the PHP one. None is required; the API is plain HTTPS.

Both clients are thin wrappers over the HTTP API. They normalize result codes and nothing else — no scheduling, no storage, no retry loops. Anything either can do, a plain HTTPS request can do too.

Official SDKs

Two official clients, published on the registry each language already uses. Install from there — the GitHub repositories are the source, not the install route.

composer require p2flux/sdk-php

npm install @p2flux/sdk

Both are server-side clients. They create payments, verify settlements and charge subscriptions from your backend; the buyer’s wallet experience is the hosted checkout, and the only thing a browser does is open it and report back what it saw. That report is a claim — your server’s verification is what marks an order paid.

Framework integrations

A framework integration is not a third SDK. It wires an official client into a framework’s container and adds nothing else — the methods you call are still the SDK’s own.

composer require p2flux/laravel

Package discovery registers the service provider, so there is nothing to add to bootstrap/providers.php. Inject P2Flux\P2FluxClient into a controller, command or job and the client is configured from config/p2flux.php. It installs no routes, no migrations, no models and no scheduler: your renewal job stays yours, and installing a package never starts billing anyone.

Getting started · Payments · Network fee in USDC · Subscriptions · Testing · Production checklist · Examples

JavaScript / TypeScript

Zero dependencies. charge() never throws on a payment outcome — an unreachable API comes back as NETWORK_ERROR / RETRY_LATER rather than an exception.

import { createP2Flux } from '@p2flux/sdk'

const p2flux = createP2Flux({
  apiUrl: process.env.P2FLUX_API_URL,
  timeoutMs: 30_000   // default 60s: a charge waits for confirmation
})

const result = await p2flux.charge(ref)
result.ok            // CHARGED or ALREADY_CHARGED
result.action        // SUCCESS | WAIT | RETRY_LATER | …
result.retryable     // safe to repeat the identical call
result.raw           // the untouched API body

PHP

PHP 8.1+, no framework and no Composer runtime dependencies. The default transport is P2Flux\CurlTransport, loaded only when no transport is given — the client itself contains no curl call, which is what lets a WordPress plugin vendor it. The constructor takes an optional transport callable, so a host application can route requests through its own HTTP stack — wp_remote_post, Guzzle — or stub them in tests.

use P2Flux\P2FluxClient;

$p2flux = new P2FluxClient([
  'apiUrl'    => getenv('P2FLUX_API_URL'),
  'timeout'   => 30,
  'transport' => fn($url, $payload, $timeout) => [$status, $body],
]);

$result = $p2flux->charge($subscriptionRef);   // never throws on an outcome

Each repository carries its own guides, runnable examples and a complete merchant integration.

PHP — Packagist · GitHub · Getting started · Payment flow · Network fee in USDC · Examples · Testing · Production checklist

JavaScript / TypeScript — npm · GitHub · Getting started · Payment flow · Network fee in USDC · Examples · Testing · Production checklist

Charging AI agents

Each client can put an x402 paywall in front of a route: a request without payment gets 402 with the price, and the payment is settled before your handler runs. You give your wallet and a price. Needs @p2flux/sdk 0.8.0, p2flux/sdk-php 0.8.0 or p2flux/laravel 0.2.0.

import { createPaywall } from '@p2flux/sdk/paywall'

const paywall = createPaywall({ apiUrl: 'https://api.p2flux.com', recipient: '0xYourWallet', price: '0.05' })

app.get('/report', paywall.express(), (req, res) => res.json(report))               // Express
export default { fetch: paywall.wrap((request) => new Response('paid content')) }   // Workers, Bun, Hono, Next

$paywall = new P2Flux\Paywall($p2flux, ['recipient' => '0xYourWallet', 'price' => '0.05']);
$result = $paywall->guard($_SERVER['HTTP_PAYMENT_SIGNATURE'] ?? null, $currentUrl, $_SERVER['HTTP_USER_AGENT'] ?? null);

foreach ($result['headers'] as $name => $value) { header("$name: $value"); }
if (!$result['allow']) { http_response_code($result['status']); echo json_encode($result['body']); exit; }
// serve the content - once per payment

// .env: P2FLUX_RECIPIENT=0xYourWallet
Route::get('/report', ReportController::class)->middleware('p2flux.paywall');          // configured price
Route::get('/data', DataController::class)->middleware('p2flux.paywall:0.20');          // this route's price
Route::get('/article/{id}', ArticleController::class)->middleware('p2flux.paywall:0.05,agents');

• One payment serves one response; the same payment presented again is refused.
• Pay per request and prepaid balance are both offered; switch prepaid off with prepaid: false.
• agentsOnly (Laravel: ,agents) lets browsers and search engines pass free. A request signed as a bot (Web Bot Auth) counts as an agent.
• An agent’s request to take back its unused prepaid balance is answered for you.

Usage pricing — when the cost is known only after the work (tokens, rows, seconds). The agent signs for at most a maximum; you charge what the request cost. The work runs only after P2Flux confirmed the payment will settle; if the settlement then fails, the result is not returned.

const result = await paywall.usage(
  { url: request.url, paymentHeader: request.headers.get('payment-signature'), maxPrice: '1' },
  async () => {
    const rows = await runQuery()
    return { amount: (rows.length * 0.001).toFixed(6), value: rows }
  },
)
if (!result.allow) return new Response(JSON.stringify(result.body), { status: result.status, headers: result.headers })
return Response.json(result.value, { headers: result.headers })

$result = $paywall->usage($_SERVER['HTTP_PAYMENT_SIGNATURE'] ?? null, $currentUrl, '1', function () {
    $rows = run_query();
    return ['amount' => number_format(count($rows) * 0.001, 6, '.', ''), 'value' => $rows];
});
foreach ($result['headers'] as $name => $value) { header("$name: $value"); }
if (!$result['allow']) { http_response_code($result['status']); echo json_encode($result['body']); exit; }
echo json_encode($result['value']);

What each client covers

Same operations, same names, in both languages — a developer switching between them recognizes every call. All 21 public V1 merchant operations, in both clients:

/health is an operational liveness endpoint, not a merchant operation; /metrics and /ready are loopback-only. None of the three belongs in an SDK.

Or use REST

No SDK is required for any part of the integration. Every endpoint is a POST with a JSON body and no authentication — see the API reference. Python and other languages have no client yet; call the API directly.

Each SDK repository carries its own documentation under docs/ — installation, environments, both payment flows, every charge outcome, recovery, allowance repair, refunds and security. The PHP repository also has framework guides, a testing guide and a runnable end-to-end example.