The problem appears when an AI agent calls an unfamiliar endpoint because it needs one job done now.
The endpoint does not offer an account, a monthly plan, or a human approval button.
It answers with 402 Payment Required, describing the token, network, amount, and recipient it accepts.
The agent signs a payment authorization and tries again.
The service verifies the authorization, settles it, and admits one job.
In Tangle’s asynchronous Blueprint, a reusable service definition, gateway, that admission returns 202 Accepted; the runner produces the result through the service’s documented result path.
That is the promise of a Blueprint, a reusable service definition, using x402, an HTTP payment protocol, for paid job admission. The payment arrives through Hypertext Transfer Protocol (HTTP), but the paid request must still become a durable, typed job that a Tangle operator, the service provider, can run and recover.
Payment first, job second
x402 is an open Hypertext Transfer Protocol (HTTP) payment protocol for machine-to-machine requests. It defines how a server says “payment is required,” how a client presents payment authorization, and how the server reports the payment response.
A Tangle Blueprint is a public service definition with named jobs and an operator-facing runtime. In a paid Blueprint, x402 is the admission layer and the Blueprint runner is the execution layer. The gateway should verify and settle the payment before it invokes an expensive paid job, then enqueue exactly one admitted job with a traceable identifier.
The payment proves that a client authorized a particular transfer under particular conditions. It does not prove that the model was correct, that the operator used the best hardware, or that the result deserves to be trusted. Those are separate verification questions.
Terms for the handoff
A Blueprint is a reusable service definition that tells Tangle what jobs exist and how operators can run them.
An operator is the person or team that supplies a machine and runs one service instance.
A runtime is the process and environment that executes the handler, including its dependencies, model, permissions, and timeout.
A GPU, or graphics processing unit, is an accelerator that may be required for model inference.
A job router maps a job type to its handler. It is the service’s dispatch table, not the model-routing service or the network component that sends packets between hosts.
An agent profile is the client’s policy for calling a service. It can include the endpoint, accepted chain and token, recipient, budget, timeout, retry rule, and the evaluation checks used to judge the result.
An evaluation is a defined check against an expected condition, such as “the response has a valid schema and the model version is the approved one.” An evaluation is evidence about one run, not a universal guarantee.
A trace is the timeline joining the HTTP request, payment proof, admitted job, runtime attempt, and result. The trace is what lets an operator explain a timeout without exposing the user’s private input.
The five-message mental model
The generic x402 flow is easiest to understand as two HTTP requests and three named headers.
The x402 repository documents PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE.
The Tangle Blueprint gateway adds an asynchronous job boundary: a settled payment produces an admitted JobCall, not an inline job result.
client Blueprint gateway operator runtime
| | |
|-- POST /jobs ------------------->| |
|<-- 402 + PAYMENT-REQUIRED -------| |
| | |
|-- POST /jobs + PAYMENT-SIGNATURE->| |
| |-- verify payment ---------------->|
| |-- settle payment ---------------->|
| |-- enqueue typed job ------------->|
| | |
|<-- 202 + PAYMENT-RESPONSE --------|<------ admitted JobCall ----------|
| | |
|------ follow documented result path ------------------------------->|The server may verify and settle locally or call a facilitator. A facilitator is a service that checks whether a payment authorization is valid and, when asked, submits or completes settlement on the network. It is a payment utility, not the job runner and not a judge of the output.
The payment response belongs to the completed payment operation. The job admission belongs to the Blueprint gateway, and the job result belongs to the Blueprint runtime. Keeping those facts separate prevents a common error: returning a success status because payment settled even though the job never ran.
A concrete request and response
Assume a Blueprint exposes summarize_document and accepts USDC, the USD Coin token, on one supported network.
The following 402 response is illustrative, but it shows the fields an agent needs before signing anything.
HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64-encoded-payment-requirements>
{
"job": "summarize_document",
"network": "eip155:84532",
"asset": "<testnet-usdc-contract>",
"amount": "250000",
"decimals": 6,
"payTo": "<operator-payment-address>",
"expiresAt": "2026-08-03T12:05:00Z",
"requestId": "req_8f2"
}The client should compare this information with its agent profile. It should refuse to sign if the network, token contract, recipient, amount, job, or expiration is outside policy.
The retry carries a payment authorization. The exact encoding and scheme depend on the supported x402 network and token, so clients should use the current x402 client documentation and the token’s official documentation.
POST /jobs HTTP/1.1
Host: summarize.example.com
Content-Type: application/json
PAYMENT-SIGNATURE: <base64-encoded-payment-authorization>
{
"job": "summarize_document",
"input": "<redacted-document-reference>"
}The PAYMENT-SIGNATURE payload can carry x402’s optional payment-identifier extension when the server advertises it.
That extension is the protocol’s current idempotency mechanism; an application may also keep its own job key, but Idempotency-Key is not an x402 header requirement.
See the payment-identifier extension before implementing retry deduplication.
For the Tangle Blueprint gateway, successful payment and job admission can return 202 Accepted:
HTTP/1.1 202 Accepted
Content-Type: application/json
PAYMENT-RESPONSE: <base64-encoded-settlement-response>
X-Job-Trace: tr_8f2
{
"status": "accepted",
"job": "summarize_document",
"callId": "call_8f2",
"result": "follow the service's documented result path"
}The X-Job-Trace field is an application convention in this example, not an x402 requirement.
A real service should choose a stable public trace identifier, document its result lookup path, and state what the trace does and does not reveal.
How the Blueprint integration fits
The software development kit (SDK) keeps payment ingress from becoming a second job implementation. The x402 path should produce the same kind of typed work that another producer can submit.
In plain language, a producer turns an external event into a job for the runner. An x402 producer turns a settled payment request into a job. An on-chain producer can turn a Tangle job event into a job. The job router then selects the same handler for both sources when the service’s policy allows it.
The public Tangle x402 gateway is implemented as a background service that pairs with a producer. The public Blueprint SDK repository is the source to check for current Rust APIs and configuration names.
The architectural boundary looks like this:
HTTP request
|
v
x402 gateway: parse, price, verify, settle, deduplicate
|
v
verified-payment job
|
v
Blueprint runner: queue, route, execute, submit result
|
v
admission response + later job result + traceThe gateway should not know how a model summarizes a document. The model handler should not know how a wallet signed a payment. The job record is the boundary between them: it contains the approved job identity, payment reference, input reference, deadline, and trace ID.
Why settle before execution?
There are two broad options.
With settle before execution, the gateway confirms that payment can complete and then starts expensive work. With execute before settlement, the service performs work first and asks the payment system to settle afterward.
The current Tangle gateway exposes a settle-before-execution path. That is a sensible default for GPU inference or long jobs because it limits unpaid compute.
The tradeoff is that settlement creates an obligation before the runtime returns an answer. If the worker then crashes, the service needs a durable recovery policy. It can retry on another operator, produce a documented failed outcome, or invoke a refund or compensation process if the payment arrangement supports one.
The payment protocol does not choose that policy for you. Write it into the service contract and expose the state to the client.
payment required -> payment verified -> payment settled -> job admitted
|
+-> running
+-> succeeded
+-> failed with recovery referenceDo not collapse verified and settled.
Verification asks whether the authorization is acceptable.
Settlement asks whether the transfer was completed or submitted according to the network and facilitator rules.
An authorization that looks valid can still fail to settle because of balance, gas, network, nonce, or token conditions.
Quotes expire for a reason
An x402 payment requirement is a temporary offer to perform a specific request under specific terms. It should be bound to the job, token, network, recipient, amount, and expiration.
The public Tangle gateway also has a quote registry for tracking quote state. The quote registry source shows the important lifecycle properties: a quote can expire, it can be consumed, and old entries can be garbage-collected. The current registry is held in gateway memory, so it helps with admission and replay checks but is not a durable payment ledger. Persist the settlement reference and job outcome separately if a paid job must survive a gateway restart.
That registry is not a substitute for on-chain payment replay protection. It is an application-level record that helps the gateway reject an already-used or expired quote before queueing work.
Use a short lifetime for volatile prices and slower client flows only when the user experience requires it. An example five-minute lifetime is a policy choice, not a universal x402 default.
The cost of a longer lifetime is price and capacity risk. If a GPU is full or a token exchange rate moves, an old quote can become unprofitable. The cost of a shorter lifetime is more retries and more opportunities for a client to abandon the flow.
Worked pricing example
Suppose an operator prices one job at 0.001 units of a native asset for internal accounting. At an illustrative rate of 3,000 USDC per native unit and a 2% margin:
base amount = 0.001 × 3,000 = 3.000 USDC
margin = 3.000 × 0.02 = 0.060 USDC
quoted = 3.060 USDC
smallest units at six decimals = 3,060,000These numbers are an example, not a current market rate. An operator must source and timestamp the rate used by its deployment and define what happens when the rate is stale.
The client should see the final token amount before signing. It should not infer the amount from an internal native-unit price because conversion rules, decimals, rounding, and markup are part of the server’s payment requirements.
Facilitators reduce integration work, not trust to zero
The x402 standard allows a resource server to verify and settle itself or use a facilitator. The facilitator normally sees payment authorization and settlement metadata required for its job. It should not need the private document or model output.
The Coinbase facilitator documentation describes the facilitator’s verify and settle role. The x402 production guidance also makes clear that teams can choose a production facilitator, self-host one, or handle verification and settlement locally where the scheme allows it.
A service still has to decide:
- Which facilitator endpoint is allowed in production.
- Which networks and schemes it supports.
- How verification and settlement timeouts are handled.
- How settlement retries avoid duplicate payment effects.
- Which metadata is retained and which is deleted.
- What happens when the facilitator says “unknown” rather than “failed.”
The safest default for unknown payment state is no execution. The service can retry a status check if the protocol supports it, but it should not treat an unreachable facilitator as approval.
Retry rules are part of the interface
An agent will retry when it receives a network timeout. That retry is not malicious; it is normal distributed-systems behavior. The service needs to distinguish these cases:
| Case | Safe result |
|---|---|
| Payment requirements received, no signature sent | Return the same or a fresh quote |
| Signature rejected before settlement | Return a clear payment failure and do not run |
| Settlement status unknown | Do not run until status is resolved |
| Settlement completed, job not yet recorded | Recover the job from the payment reference |
| Job recorded, client timed out | Return the existing job result on retry |
| Job already completed | Return the stored result, not a second execution |
An idempotency key is a client-provided label that lets the service recognize retries of the same intended operation. It does not replace payment replay protection. Store both the idempotency key and the payment reference when accepting production money.
If a job is not safe to run twice, make the handler itself idempotent or serialize retries by job ID. If a job is safe to run twice but expensive, record the duplicate and charge according to the published policy. Silence is the worst policy because the client cannot tell what happened.
Observability for one paid call
Log identifiers and durations, not private payloads. At minimum, a trace should join:
request_id
payment_requirement_id
payment_verification_result
settlement_reference
service_id / job_index
operator_or_instance_id
artifact_digest
queued_at / started_at / finished_at
evaluation_resultThe trace should answer “where did the time go?” In this sample trace, payment verification took 400 ms, queueing took 2 seconds, and model execution took 18 seconds, so the user needs a different fix than if the entire trace stops after settlement.
The trace should also answer “what did we promise?” Keep the exact token, network, amount, recipient, expiration, and job policy associated with the payment record.
What x402 does not prove
A successful payment does not prove correctness. Use deterministic output checks, redundancy, a cryptographic proof, a TEE attestation, or another job-specific method when correctness matters.
A facilitator does not prove operator availability. It can report a payment result while the runner is down. Health and recovery belong to the service.
A quote does not reserve infinite capacity. The service must enforce queue limits and reject new work before payment when it cannot honor its latency policy.
A trace does not make private data public. Redact inputs and outputs, and publish only the identifiers required for support and verification.
A working example does not establish production support. Check the current SDK release and network/token documentation before copying package names or addresses into a deployment.
The implementation decision
Use x402 when a client should discover a price and pay for a bounded HTTP capability without creating an account. Use the Blueprint runner when that capability needs an operator-run job lifecycle, Tangle integration, or a service-specific verification path.
The durable implementation is small in concept: payment requirements, payment authorization, settlement result, one admitted job, one runtime attempt, and one trace. If any of those objects is missing, the service can collect money without being able to explain what happened next.
Is x402 the same thing as a Blueprint?
No. x402 defines an HTTP payment exchange. A Blueprint defines runnable jobs, operator requirements, and the service lifecycle that executes those jobs.
Does the client pay before the job runs?
In the settle-before-execution path, the service settles payment before invoking the paid handler. That reduces unpaid compute but requires a recovery policy for a worker failure after settlement.
Can any operator run an x402-paid job?
That depends on the service’s routing and operator policy. The HTTP gateway admits a paid request, while the Blueprint runner and network rules determine which operator instance receives and executes it.
What should an x402 client verify?
It should verify the job, network, token contract, amount, recipient, expiration, scheme, and its own budget before signing. It should also use an idempotency key and know how to retrieve a result after a timeout.
Does the gateway need to expose the model input to the facilitator?
No. The payment service should send only the metadata required for payment verification and settlement. Keep private job inputs inside the service path.
Public sources
The x402 protocol repository documents the current HTTP messages and production options. The x402 buyer quickstart covers client-side payment behavior. The payment-identifier extension documents the current retry and deduplication mechanism. The Coinbase facilitator guide explains verification and settlement roles. The Tangle Blueprint repository contains the public SDK, gateway, and quote-registry implementation. The Tangle pricing and payments guide describes on-chain pricing and job quote concepts that can complement an x402 ingress path. The deployment architecture guide explains where that ingress sits beside a remote runner. The facilitator guide covers the availability and trust boundary around verification and settlement.