USAGE-BASED FRICTION PRODUCT
Send one bounded document record; receive a deterministic, reviewable plan for classification, naming, folder placement, and duplicate signals.
POST endpoint — not a webpage: https://friction-product-commerce-production.id4-score.workers.dev/v1/x402/document-classify-rename-plan
Opening that product URL in a browser sends GET and returns HTTP 405 by design. Use the unpaid POST example below.
PAYMENT CONTRACT
The accepted contract is x402 v2 exact payment: 0.01 USDC (10,000 atomic units of native USDC) on Base Mainnet eip155:8453. Current commercial availability is time-dependent; a listing or a healthy process is not a payment authorization.
Read the actual HTTP 402 challenge and verify network, asset, amount, recipient, and expiry before approving a payment. The health document reports process state; HTTP 200 there does not prove commercial admission or marketplace dispatch.
Idempotency-Key: UUIDv4, exactly 36 characters.Receipt-Recovery-Key: 32 random bytes encoded as 43-character unpadded base64url. Keep it private.Request-Digest: returned by the service; 64 lowercase hexadecimal characters.PAYMENT-SIGNATURE: x402 v2 payment payload, added only to the paid retry.SAFE QUICKSTART
A schema-valid POST without commercial headers can return a stateless HTTP 402 challenge with no request digest. To prepare a durable attempt, generate and retain one UUIDv4 idempotency key and one private recovery key before the request and set them as local environment variables. A paid retry requires both valid keys. This example contains synthetic document content and no payment signature.
curl --request POST \
'https://friction-product-commerce-production.id4-score.workers.dev/v1/x402/document-classify-rename-plan' \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--header "Receipt-Recovery-Key: $RECOVERY_KEY" \
--data '{
"originalFilename": "sample-invoice.pdf",
"extension": "pdf",
"size": 48217,
"textExcerpt": "Invoice INV-1007. Invoice date 2026-09-01. Total due $125.00.",
"metadata": {
"sourceType": "email-attachment",
"title": "Sample invoice"
},
"createdAt": "2026-09-01T12:00:00.000Z",
"folderContext": {
"knownDocuments": []
}
}'Expected result: HTTP 402 with PAYMENT-REQUIRED and Request-Digest response headers. A malformed key is HTTP 400 rather than a payment challenge.
originalFilename: string, 1–500 characters.extension: string, 1–16 characters.size: integer, 0–10,000,000,000.textExcerpt: string, up to 50,000 characters.metadata: required object; use {} when none is available.createdAt: UTC timestamp, 20–24 characters, with optional milliseconds.metadata allows up to four keys: author (500), title (1,000), sourceType (100), and a 64-hex contentHash.folderContext.knownDocuments: up to 1,000 records. Each requires id (1–128), filename (1–500), and integer size in the same range; optional contentHash is 64 hex.After your x402-capable client verifies the actual challenge and you explicitly approve one payment, retry the same POST endpoint with the exact same body, Idempotency-Key, and Receipt-Recovery-Key. Include the returned Request-Digest and add PAYMENT-SIGNATURE. Do not generate a new body or new keys for that retry.
This page does not provide a payment script, connect a wallet, submit the request, sign, or authorize a purchase.
RESULT INTERPRETATION
HTTP 200 with top-level status: SUCCESS. The output has a supported classification and a reviewable filename/folder plan.
HTTP 200 can still return output validation status: REVIEW. Treat null or uncertain proposals as a human-review instruction, not permission to guess or mutate a file.
Ordinary request errors include HTTP 400 for commercial/query controls, 405 for the wrong method, 413 for request size, 415 for content type, and 422 for body schema. Correct the request; do not treat these as paid-product availability evidence.
HTTP 503 indicates commercial trust, facilitator, execution, fulfillment, persistence, or recovery availability may be unavailable. Stop before payment or blind retry and preserve diagnostics.
LOST RESPONSE OR UNCERTAIN SETTLEMENT
Before payment, retain the exact body, UUIDv4 Idempotency-Key, private Receipt-Recovery-Key, and returned Request-Digest. If the paid response is lost or settlement is uncertain, stop automatic retries.
curl --request GET \
"https://friction-product-commerce-production.id4-score.workers.dev/v1/receipts/by-idempotency/$IDEMPOTENCY_KEY" \
--header "Receipt-Recovery-Key: $RECOVERY_KEY" \
--header "Request-Digest: $REQUEST_DIGEST"Recovery requires the original idempotency key in the path plus the original private recovery key and request digest headers. Invalid credentials and unknown receipts are deliberately collapsed to HTTP 404. HTTP 202 can represent an unfinished/reconciling receipt; HTTP 409 can represent a failed receipt; HTTP 503 means recovery is unavailable. None authorizes a second payment.
One state does not prove either of the others.
Contact pilot@friction.systems with the UTC timestamp, endpoint, HTTP status, non-secret request ID, and request digest.
Do not send the recovery key, payment signature, wallet secret, or supplied document text. No refund policy, response-time SLA, encryption assurance, or legal assurance is stated by this guide.
PRODUCT BOUNDARY
D-007 receives the document record, textExcerpt, and metadata supplied in the API request. It does not upload or read the binary document itself.
MATCH, NO_MATCH, or UNKNOWN status;PLAN or REVIEW validation status.