x402 integration

x402 is an HTTP payment protocol. A server returns HTTP 402 Payment Required with a machine-readable payment requirement.

The client pays under that requirement. It then repeats the request with a payment response.

GhostClaw adds a confidential settlement scheme to this standard request pattern.

Scheme purpose

The GhostClaw scheme keeps the x402 merchant identity and service flow. It replaces a public transfer amount with a proof-backed private note transition.

The scheme name is ghostclaw-confidential-x402-v2.

The merchant can use the same resource endpoint for standard x402 and GhostClaw. The requirement tells the client which scheme to use.

Message sequence

Initial request

The agent gives ghostclaw_fetch the target URL and request parameters.

The local client saves a normalized request representation. Normalization gives the same digest for the same method, URL, headers, and body.

The client sends the request without a payment response. The merchant returns either the resource or HTTP 402.

Payment requirement

The HTTP 402 response contains one or more payment options. A GhostClaw option contains the confidential scheme identifier.

A complete requirement binds these values:

The amount is visible to the payer and merchant. It does not become a public input in the Base payment call.

Requirement validation

The client validates the requirement before it selects a note.

It checks the TLS origin, scheme, chain, asset, pool, merchant identity, note key, amount, request digest, nonce, and expiry.

It also checks the human spending policy. A rejected requirement does not start proof creation.

The client treats a changed quote as a new requirement. It does not reuse proof data from the old quote.

Request binding

The client creates a random 256-bit salt. It combines the salt with the normalized request and requirement data.

The payment circuit hashes these values into the public payment intent.

The salt stays in the private payment response. The public Base transaction contains only the payment intent.

The merchant recomputes the payment intent from its saved request and the received salt.

This binding prevents these substitutions:

• A different merchant.
• A different amount.
• A different asset.
• A different pool.
• A different resource.
• A different request body.
• A different requirement nonce.

Local payment construction

The wallet selects one available private note. It creates one merchant output and one payer change output.

The payment proof binds the public payer, public merchant, owner values, payment intent, output commitments, nullifier, and accepted root.

The amount stays private inside the proof. The proof enforces value conservation and correct output commitments.

The wallet encrypts the merchant note with the note key from the requirement.

Settlement response

After Base accepts the transaction, the client builds the GhostClaw payment response.

The response contains the data that the merchant needs for validation:

The response does not include the payer input note or payer change note plaintext.

Paid retry

The client repeats the original HTTP request. It includes the payment response in the selected x402 payment header.

The request method, URL, headers, and body must match the values used for the payment intent.

The merchant rejects a paid retry when the request changed after payment construction.

Merchant verification

The merchant performs service-level and chain-level checks.

Service-level checks

1. The requirement exists and has not expired.
2. The paid request matches the saved request.
3. The scheme, network, asset, pool, and merchant match.
4. The request salt recreates the payment intent.
5. The payment intent has not delivered another resource.

Chain-level checks

1. The transaction succeeded on the required chain.
2. The transaction destination is the configured pool.
3. The function is the confidential payment function.
4. The receipt contains the matching settlement event.
5. The event payer and merchant match the requirement.
6. The event payment intent matches the response.
7. The event output commitments match the response.
8. The new root contains the merchant commitment.

Note checks

1. The merchant decrypts the fixed-size note envelope.
2. The decrypted amount equals the quoted amount.
3. The decrypted owner matches the merchant identity.
4. The decrypted fields recreate the event commitment.

The merchant records the payment intent before it releases the resource. This order prevents concurrent delivery replay.

Facilitator role

An x402 facilitator can help a merchant validate or submit payments. A standard facilitator must understand the selected payment scheme.

A facilitator that supports only public token transfer cannot fully validate a GhostClaw confidential payment.

A GhostClaw-aware facilitator must verify the Base receipt, settlement event, request binding, commitment, and replay state.

The merchant can perform these checks directly. The facilitator is an optional service boundary, not a proof authority.

The Base verifier remains the authority for proof validity. A facilitator cannot accept an invalid proof on behalf of the contract.

Standard x402 compatibility

GhostClaw keeps the standard HTTP control flow:

request
402 requirement
payment construction
paid retry
resource response

It adds scheme-specific fields for the pool, proof-backed settlement, note encryption, and payment intent.

An x402 router can advertise several schemes. The client selects GhostClaw when both payer and merchant support it.

Agent behavior

The agent does not construct protocol fields. It requests the URL through ghostclaw_fetch.

The local wallet interprets the requirement and enforces the human policy. It returns the resource or one structured error.

The agent can ask the human for an action when setup, funding, policy, or recovery requires human control.

Durable jobs

A paid service can complete after the HTTP request ends. The merchant returns a durable job handle after settlement.

The job handle identifies the paid result. It does not authorize a second payment.

The payer can poll or retrieve the result with the same handle. The merchant must make this retrieval idempotent.

Delivery failure

Base settlement and HTTP delivery are separate events. A network failure can occur after payment finality.

The client saves the transaction hash, intent, and delivery handle. It checks settlement before any retry that can create payment.

When settlement exists, the client retries delivery only. It does not create another proof or payment.

Privacy properties

The merchant learns the amount because it issued the requirement. The payer learns the amount before it approves payment.

The sponsor and Base see the settlement identities and proof. They do not receive the private amount through the GhostClaw call.

The public event gives marketplaces an accountable payer and merchant pair. It does not give them the transaction price.

Read Payment flow for the full state sequence. Read Wallet and agents for policy enforcement.