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 exists so developers do not have to embed payment orchestration, approval logic, and receipt handling into every agent host.
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, approvals, and receipts 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 approved the prepared state.
AgentHarness
Expose the prepare, execute, and result flow behind a canonical three-tool surface when a model host needs a stable contract.
Integration notes
What good adoption looks like.
The simplest proof is usually the best proof: one request, one identity, one hosted 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, approvals, and receipts 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.
Escalate only when the request needs it
The host stays deterministic while 402flow turns policy and approval into explicit product paths instead of app-specific conditionals.
Next step
Pair the SDK with the hosted merchant proof surface.
The SDK is the clearest adoption path. The hosted demo merchant gives you a bounded place to test request shaping, payment execution, and receipt persistence together.