Docs
This page is the shortest path to a useful first integration: install the SDK, create one client, choose the right request path, and understand how 402flow handles observing paid traffic, policy denials, rail selection, and receipt finality.
Start here
import {
AgentHarness,
AgentPayClient,
defaultHarnessInstructions,
defaultHarnessToolSpecs,
} from '@402flow/sdk';
const client = new AgentPayClient({
controlPlaneBaseUrl: 'https://api.402flow.ai',
organization: 'acme-labs',
agent: 'research-worker',
auth: {
type: 'bootstrapKey',
bootstrapKey: process.env.X402FLOW_BOOTSTRAP_KEY ?? '',
},
});
const harness = new AgentHarness({ client });
console.log(defaultHarnessInstructions);
console.log(defaultHarnessToolSpecs.map((spec) => spec.name));
// [ 'prepare_paid_request', 'execute_prepared_request', 'get_execution_result' ]Quickstart
You do not need a large implementation plan to evaluate 402flow. One request path is enough to prove the model.
Start from `npm install @402flow/sdk` and keep the integration surface small.
Use `AgentPayClient` with your control-plane base URL, organization, and agent identity.
Use `fetchPaid(...)` when the request is already known, or prepare/execute when the agent needs to reason about the request first.
Prove one end-to-end paid request against the demo, then compare it with a policy denial or observed-only discovery case before you broaden the integration.
Choose a path
Most integration choices collapse to one question: do you already know the request, or does the caller need to inspect and revise it first?
fetchPaid(...)
Use this when the host already knows the merchant URL, method, headers, and body and just needs the shortest governed execution path.
prepare + execute
Use this when the application or orchestrator wants direct control over the prepared request. You inspect parameter hints, validation issues, and the next action, then decide when to execute.
AgentHarness
Use the harness when the caller is a model host. AgentHarness exposes the same prepare, execute, and result lifecycle through a stable three-tool contract with default instructions.
Platform model
402flow does more than pay a challenge. It keeps merchant discovery, policy decisions, and rail selection explicit and reviewable.
Under Default allow and monitor, 402flow can track spend against merchants that are not yet configured in Setup. Those merchants appear in Reports as observed-only until the org decides to promote them.
When a managed request does not satisfy policy, 402flow denies it before execution and creates a policy review event. Operators adjust policy for future traffic instead of approving one request at a time.
When a merchant advertises multiple compatible rails, 402flow follows the enabled wallet order to pick the highest-precedence compatible path. The rule is explicit, deterministic, and visible in receipts and reports.
Policy model
The same policy model can express an org-wide cap, a merchant-specific budget, an agent-specific limit, or a shared budget across selected merchants or agents. It can also enforce a single-request ceiling or a day, week, or month window before execution proceeds.
A policy can apply org-wide or to merchant- and agent-scoped traffic. Non-org scopes can target selected sets of merchants or agents, or all merchants or agents, and can apply either as a shared cap or a per-member cap.
Limits can deny a single request based on its current amount, or evaluate cumulative spend over day, week, or month windows before execution continues.
Policies are amount-based and asset-aware, so org caps, merchant budgets, and agent spend limits all use one structured model instead of ad hoc rules in app code.
Example stack
A single request can match all three. 402flow evaluates the current request amount together with any applicable time-window usage before execution continues.
Shared vs per-member
Shared policies pool usage across every matching merchant or agent. Per-member policies keep separate headroom for each matching merchant or agent inside the same selected set.
Runtime notes
These are the details worth knowing before you wire the SDK into a real paid-request path.
Node 20+ is the current supported runtime.
Replayable request bodies matter early: use strings or URLSearchParams for paid prepare and execute flows.
Bootstrap-key auth is the recommended default for most SDK integrations.
Organizations can start with either "Deny by default" or "Default allow and monitor," depending on whether they want strict blocking or observed-only merchant discovery first.
Receipt finality can be provisional first; the chain observer later promotes confirmed receipts once the onchain finality rule is satisfied.
Next step
The next useful move is not more reading. It is one governed paid request through the SDK, the demo-merchant, and the lifecycle you expect to operate in production.