How recuut works
Learn which parts of a paid request belong to recuut, your application, and the payer.
recuut sits between a seller application and a payer for the payment part of a request. Your server asks recuut whether it may release a protected result, and recuut answers with free access, payment instructions, or a completed payment.
The merchant is the seller account. The payment boundary is the point where your server asks recuut for access. An agentic wallet is software that can read payment instructions, approve them under a limit, and retry the request.
| Participant | Job |
|---|---|
| Your application | Identifies the resource, validates input, performs the protected work, and reports its outcome. |
| recuut | Owns prices, accepted payment methods, settlement coordination, payout policy, and transaction records. |
| Payer or agentic wallet | Requests the resource, follows x402 payment instructions when needed, and retries with payment proof. |
A caller cannot choose the merchant account, price, environment, or payment method through request input. Your server keeps the merchant API key. The payer only receives the payment instructions needed for its own request.
You can sell an API response or another digital item. A resource identifies the item. A published revision defines the values your application reports. A price determines what the payer is asked to pay; a free revision asks for nothing and records the execution.
A paid request
- The payer calls your protected URL. For revisions with input variables, your application validates input before asking recuut for access. Without input variables, FastAPI can return
402before validating the body. - recuut reads the resource, its published revision, and the active price. If payment is required and the request has no valid payment proof, your application returns HTTP
402unchanged withPAYMENT-REQUIRED. - The payer's wallet reads the payment requirements, prepares payment proof, and repeats the same request with
PAYMENT-SIGNATURE. The merchant API key never leaves your server. - When access succeeds, your application performs the work. If the revision has output variables, it reports every required variable using that revision's exact names and rules.
- Your application completes the transaction and releases the protected result with
PAYMENT-RESPONSEonly after a successful completion.
Streaming protected responses are not supported because completion must finish before the result is released. x402 payment instructions and retry explains each header.
Access, execution, and completion
| Step | recuut | Your application |
|---|---|---|
| Access | Applies the active payment policy and checks payment proof. | Validates input and identifies the protected resource and revision. |
| Execution | Keeps the request's payment state. | Performs the protected work and reports revision-required values. |
| Completion | Finishes the transaction and records the outcome. | Releases the result only after successful completion. |
Each recuut response has one server branch:
| recuut response | Server branch |
|---|---|
Access 402 | Return the JSON body and PAYMENT-REQUIRED; do no protected work. |
Access 200 with no transaction ID | Perform and return the free result, then report its execution metadata. |
Access 200 with a transaction ID | Perform the work, retain the result privately, then call completion. |
Completion 200 + succeeded | Return the result with PAYMENT-RESPONSE. |
Completion 202 + settling or reconciling | Keep the result private and query the transaction by ID. |
Completion 200 + failed, or any error | Return a safe failure and inspect the transaction before retrying side effects. |
202 exists because settlement can outlive one HTTP request. It means recuut accepted the completion request but cannot yet prove the payment outcome. Poll Get a transaction with bounded waits, and honor Retry-After when it is present. succeeded and failed are final; settling and reconciling are not.
Completion may include safe execution metadata: the HTTP status, elapsed milliseconds, response media type, and response size in bytes. recuut does not accept the response body, response headers, or exception message. A maintained framework integration reports a returned 4xx or 5xx response as failed and does not settle the transaction.
Network interruptions can repeat a request. Follow Errors and retries before retrying work with side effects.
If your framework has a recuut integration, it manages this boundary for you. A direct HTTP integration makes the same Merchant API calls explicitly.
Build a direct HTTP integration → · Learn about resources and revisions →