Getting paid using 4Mica

Executive Summary

4Mica is a cryptographic credit system for web3. It lets a payer consume a service immediately while settlement happens later. Recipients get a guarantee that is enforceable on-chain if the payer defaults. Payers keep collateral productive in the vault, earning yield and giving credit to the payers; recipients get payout protection.

This post explains how to accept payments using 4Mica, including V2 guarantees where remuneration is gated by ERC-8004 validation status (for example via 8004 ValidationRegistry and wachai-validation-sdk).

V1 vs V2: Quick Difference

• V1: standard credit guarantee. If payer defaults, recipient can remunerate after grace period and before tab expiry.
• V2: same credit flow plus signed validation policy fields (registry, validator, agent, score threshold, optional tag).
• V2 enables 8004 verification: remunerate only succeeds when ERC-8004 validation status matches the signed policy.
• Both versions are supported; version is derived from the signed claims payload.

System Map: Who Does What

A 4Mica transaction is a choreography between five actors:

• Payer (AI agents, users): Have collateral in the vault which backs their credit, then settle on-chain before the tab expires (default 21 days). Earn yield on the collateral.
• Recipient (resource server): serves protected APIs that require payments. Responsible for configurating the tabs (ttl, asset), verify user credit, ask for credit guarantees, and in case of defaults, initiate the settlement process.
• Facilitator: This is any x402 facilitator, integrated with 4Mica. Responsible for providing payment information for the 4Mica credit flow.
• 4Mica Operators: Where the magic happens. Minting tabs, issuing guarantees, and managing the overall credit flow.
• Vault: Where agents deposit collateral to back their credit. It holds custody; withdrawals are requested first and can be finalized after the withdrawal grace period (default 22 days) once outstanding credit is handled.

x402 Primer: HTTP 402 + Payment Requirements

x402 is an open, HTTP-native payment standard. It activates HTTP 402 Payment Required so a resource can advertise how it wants to be paid, then lets the client retry the same request with a payment header.

In the 4Mica credit flow, the x402 scheme string is 4mica-credit and the client sends a versioned payment header: X-PAYMENT for v1, PAYMENT-SIGNATURE for v2 (both are base64 JSON envelopes). The resource server delegates verification and settlement to the x402-4mica facilitator.

• 402 responses advertise scheme, network, payTo, asset, maxAmountRequired (v1) or amount (v2), and extra.tabEndpoint.
• For v2, paymentRequirements.extra should include validationRegistryAddress, validatorAddress, validatorAgentId, minValidationScore, and validationChainId (plus optional requiredValidationTag). validationChainId must match network (eip155:<chainId>).
• Clients retry with the payment header (X-PAYMENT for v1, PAYMENT-SIGNATURE for v2); resources call /verify for structural checks and /settle to obtain a certificate.
• If the header is missing or invalid, return 402 again with the same requirements and an actionable error.

Concept Glossary

Here are the key primitives you will see across the docs and SDKs:

• Tab: Line of credit between payer and recipient for a specific asset.
• paymentRequirements: the x402 payload the recipient advertises in a 402 response (scheme, network, payTo, asset, maxAmountRequired).
• tabEndpoint: a recipient-owned endpoint listed in paymentRequirements.extra.tabEndpoint. The payer calls it to bind requirements to a wallet and receive a tab.
• PaymentGuaranteeRequestClaims: the signed request from the payer (tab_id, recipient, asset, amount, timestamp). V2 extends this with a validation policy.
• Payment header: the base64 header wrapping the signed claims (X-PAYMENT for v1, PAYMENT-SIGNATURE for v2). Recipients pass it to /verify and /settle.
• PaymentGuaranteeClaims: the upgraded claims produced by core. It adds domain, version, req_id, and total_amount.
• Certificate: the signature over PaymentGuaranteeClaims returned by /settle. This is the cryptographic proof of the credit. If the user defaults, the recipient can remunerate after the grace period (default 14 days) and before the tab expires (default 21 days). For V2, remuneration additionally requires passing ERC-8004 validation checks on-chain.
• Validation policy (V2): signed fields include validation_registry_address, validation_request_hash, validation_chain_id, validator_address, validator_agent_id, min_validation_score, validation_subject_hash, and required_validation_tag.
• Grace periods: By default, tabs expire after 21 days and the remuneration grace period is 14 days, leaving a 7-day window to remunerate after default. Withdrawal requests finalize after a 22-day grace period.

SDK Installation

Pick the SDK that matches your stack. Source repos: ~/4mica-core/sdk, ~/py-sdk-4mica, ~/ts-sdk-4mica.

Return 402 Payment Required

When a request arrives without a valid payment header, respond with HTTP 402 and include paymentRequirements so the client can request a tab and retry.

The requirements must match what you will later verify: the amount must equal maxAmountRequired, and scheme, network, payTo, and asset must match the tab you issue.

Handle User Requests (Recipient Logic)

1. If the payment header is missing, return 402 with paymentRequirements and extra.tabEndpoint.
2. If present, call /verify with { x402Version, paymentPayload, paymentRequirements } (where paymentPayload is the decoded payment header).
3. If /verify returns invalid, return 402 again (optionally with the invalidReason).
4. If valid, call /settle to mint a certificate once you are ready to accept credit.
5. Persist the certificate, then serve the protected response immediately. You can also fetch all your certificates later if needed.

Only /settle touches the 4Mica operator to issue a BLS certificate. /verify is purely structural and is safe to use as a preflight check before doing any expensive work.

For V2, /settle does not prove the job outcome; it only issues a certificate with the signed validation policy. The ERC-8004 validation check is enforced later during on-chain remuneration.

Integrate 4Mica with Code Samples

Below is a step-by-step, SDK-only integration for the 4Mica credit flow. Each step includes Rust, Python, and TypeScript variants.

The snippets focus on the SDK calls; wire them into your existing HTTP 402 responses, tabEndpoint handler, and request retries.

Step 1: Create or Reuse a Tab (Recipient SDK)

Your resource server creates a tab for the user and chooses the asset + TTL. The recipient signer must match the payTo address you advertise.

Step 2: Sign the Payment Header (Payer SDK)

The payer consumes the paymentRequirements from the 402 response, refreshes the tab if needed, and signs the guarantee to produce the base64 payment header (X-PAYMENT for v1 or PAYMENT-SIGNATURE for v2).

SDK behavior is automatic: if V2 validation fields are present in paymentRequirements.extra, claims are built as V2 with canonical validation_subject_hash and validation_request_hash; otherwise V1 is used.

Step 3: Settle via the Facilitator (SDK helper)

If you delegate settlement to an SDK helper (for example a backend job or a payer-assisted flow), call settle_payment with the signed header and original requirements to obtain the certificate.

Step 4: Pay the Tab On-Chain (Payer SDK)

When it is time to settle, the payer uses the req_id from the certificate to repay the tab in the same asset that was used when the tab was opened.

Minimal Flow (x402 Credit)

1. Recipient returns 402 Payment Required with paymentRequirements and extra.tabEndpoint.
2. Payer SDK calls the tabEndpoint, which forwards to POST /tabs to open or reuse a tab.
3. Payer signs a guarantee and retries with the payment header.
4. Recipient optionally calls /verify (structural checks) and then /settle (issues the certificate).
5. Recipient delivers the protected response immediately; payer settles on-chain later (payTab or payTabInERC20Token).

This is the “agent pays with credit” experience: the recipient opens the tab, the agent gets a guarantee via /settle, and the agent settles later on-chain before the tab expires (default 21 days). If unpaid, recipients can remunerate after the grace period (default 14 days). V2 claims add a mandatory ERC-8004 validation gate before remuneration succeeds.

Sequence Diagram (Minimal Flow)

Below is a compact sequence view of the minimal x402 path with the key handoffs:

What /verify vs /settle Actually Do

/verify is purely structural: it decodes the payment header and ensures the claims match the recipient’s advertised requirements. It does not talk to core and does not issue a certificate.

/settle repeats the same checks and then calls core to request a BLS guarantee. The facilitator verifies the certificate locally and returns it to the recipient.

• /verify returns { isValid, invalidReason?, certificate: null }.
• /settle returns { success, networkId, txHash, certificate }.
• Both enforce scheme/network, payTo, asset, and exact amount matching.
• For V2, neither endpoint confirms job validity; they only carry and enforce claim structure. Job validity is checked later through ERC-8004 validation status during remunerate.

Happy Path: Payer Settles On-Chain

1. Recipient receives a certificate from /settle and serves the request.
2. Payer later calls payTab (ETH) or payTabInERC20Token (ERC20) with tabId, req_id, amount, and recipient.
3. The contract records the payment and emits events; core unlocks collateral and the tab appears as settled to the recipient.

The req_id used here is the one embedded in the certificate returned by /settle. This is how the chain ties a specific guarantee to a specific repayment.

Default Path: Recipient Remunerates

1. If the payer does not settle before the grace period, the recipient (or a daemon) lists pending remunerations.
2. For V2, ensure the linked ERC-8004 validation request has a passing status (for example by calling getValidationStatus from wachai-validation-sdk).
3. The recipient verifies the certificate and calls Core4Mica.remunerate with the certificate bytes and BLS signature.
4. The contract validates domain, timestamp + grace window, tab status, and collateral; for V2 it additionally validates ERC-8004 response constraints from the signed policy before transfer.

This path is deterministic: the same certificate that enabled instant delivery becomes the claim that makes the recipient whole, but V2 only pays out after validated job evidence exists on-chain.

Tab Lifecycle, TTL, and req_id Rules

Tabs are reused for the same payer/recipient/asset until the TTL expires. Each guarantee increments req_id and updates total_amount in the certificate. The contract rejects out-of-order req_id or asset mismatches. This is how replay and double-spend attempts are prevented.

• Tabs can be created for ETH or ERC20 assets.
• The tab’s startTimestamp is derived from the first valid guarantee.
• Claims must fall within the tab’s active time window.

Two Ways to Integrate

• x402 flow: recipients expose a tabEndpoint and call /verify + /settle. Payers use the SDK to sign the versioned payment header.
• Direct core flow: recipients create tabs and request guarantees via the SDK, then remunerate directly. This is useful for closed systems or internal pipelines.

Optional Exact / Debit Fallback

If operators configure an exact (debit) backend, the facilitator can route /verify and /settle to that path instead. Responses mirror upstream x402 debit flows and may include transaction hashes rather than certificates.

Why This Design Holds

4Mica keeps the happy path off-chain but preserves enforceability on-chain. Recipients never need to trust a coordinator; they only need a certificate that the contract will accept. Payers keep capital efficient, and the system has a clear and auditable failure mode: either the payer pays, or the recipient remunerates (for V2, only after ERC-8004 validation passes).