Add pay-per-call billing without giving up your API gateway.

One simple execution order

1. Create a Challenge for the current request.
2. If no payment signature exists, return HTTP 402 with paymentRequiredHeader.
3. When a signature is present, call Verify with the same request descriptor.
4. Run your business logic only after verification.
5. After success, call Settle and return paymentResponseHeader to the caller.

Setup

In the merchant console, provide a Base receiving address, create an API service, and price exact methods and paths in USDC. The service key is shown once.

LAVOLOOP_API_URL=https://api.lavoloop.com
LAVOLOOP_SERVICE_TOKEN=lv_service_...

1. Challenge

POST, PUT, and PATCH require bodySha256; hash the exact received bytes as lowercase hex SHA-256. GET and DELETE may omit it.

POST https://api.lavoloop.com/v1/merchant/x402/challenges
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Content-Type: application/json

{ "request": {
  "method": "POST",
  "path": "/v1/render",
  "query": "format=png",
  "bodySha256": "<sha256-of-exact-request-bytes>"
} }

The response includes challengeId, the complete paymentRequired object, and a ready-to-return paymentRequiredHeader.

2. Verify

POST https://api.lavoloop.com/v1/merchant/x402/verifications
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Content-Type: application/json

{ "challengeId": "mch_...",
  "paymentSignature": "<PAYMENT-SIGNATURE header value>",
  "request": { "method": "POST", "path": "/v1/render",
    "query": "format=png", "bodySha256": "<sha256>" } }

A successful verification returns a short-lived settlementToken. Execute the business operation now.

3. Settle

POST https://api.lavoloop.com/v1/merchant/x402/settlements
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Idempotency-Key: <stable-key-for-this-business-operation>
Content-Type: application/json

{ "challengeId": "mch_...", "settlementToken": "lvst1...." }

The success response contains the onchain transaction and paymentResponseHeader. A safe retry with the same Idempotency-Key returns the same settlement.

Failures and retries

• Business failure: do not call Settle; the payment is not settled.
• Side-effecting work must use idempotency in your own system.
• One payment signature cannot be reused for a different path, query, or body digest.
• If a service key leaks, rotate it in the console; the old key stops immediately.

Let a merchant agent implement it

The repository includes a LavoLoop integration Skill. Once installed, a coding agent detects your framework, wires the three endpoints, adds idempotency, and runs tests.