What you keep in app code
- Which merchant route the application wants to call.
- Which agent identity and organization the request belongs to.
- How the host reacts to the returned merchant result.
SDK
A small integration surface for governed paid requests.
The SDK provides easy access to paid endpoints and keeps payment orchestration, policy logic, and receipt-finality handling out of every agent host. Callers can succeed immediately while the control plane and chain observer own settlement confirmation. It also provides tools so AI agents can shape the request through a prepare-and-execute loop.
QuickstartView repo
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' ]Developer path
Start with one paid-request flow.
Use the SDK to prove the shortest end-to-end path first, then expand into the explicit prepare and execute loop when the host needs inspection and revision.
The goal is not a second control plane in the app runtime. The goal is an easy integration surface that still keeps policy, chain observation, and receipt finality centralized.
Core surface
Four entry points, one governed request model.
Choose the surface that matches how much control the host needs before it pays.
fetchPaid(...)
Use the fast path when the application already knows the request shape and wants the shortest probe-authorize-pay-return flow.
preparePaidRequest(...)
Use the explicit preparation step when the host or model needs merchant hints, validation issues, and an authoritative next action before paying.
executePreparedRequest(...)
Execute the exact prepared request without re-probing first after the host has accepted the prepared state.
AgentHarness
Expose a stable prepare, execute, and result tool flow when a model host needs the agent to reason about request params before paying.
Integration notes
What good adoption looks like.
The simplest proof is usually the best proof: one request, one identity, one hosted demo-merchant route, then iterate from there.
Keep the request surface small
The SDK should stay thin. Your application or model shapes the request once and lets 402flow own policy, denials, receipts, and chain-observer-backed finality around it.
Use the hosted demo early
The fastest way to prove integration fit is to run the SDK against the first-party demo merchant instead of reasoning about the protocol on paper.
Keep finality out of the runtime
The host stays deterministic while 402flow turns observed-only discovery, policy review events, and chain-observer confirmation into explicit product paths instead of app-specific conditionals.
Next step
Pair the SDK with the hosted demo proof surface.
The SDK is the clearest adoption path. The hosted demo gives you a bounded place to test request shaping, payment execution, provisional receipts, and later chain-observer confirmation together.