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, and how each possible scenario is handled (happy path, default path, and optional exact/debit fallback).

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 an X-PAYMENT header (a base64 JSON envelope with x402Version: 1). The resource server delegates verification and settlement to the x402-4mica facilitator.

• 402 responses advertise scheme, network, payTo, asset, maxAmountRequired, and extra.tabEndpoint.
• Clients retry with X-PAYMENT; 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).
• X-PAYMENT: the base64 header wrapping the signed claims. 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).
• 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 X-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 X-PAYMENT is missing, return 402 with paymentRequirements and extra.tabEndpoint.
2. If present, call /verify with { x402Version, paymentHeader, paymentRequirements }.
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.

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 X-PAYMENT (Payer SDK)

The payer consumes the paymentRequirements from the 402 response, refreshes the tab if needed, and signs the guarantee to produce the base64 X-PAYMENT header.

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 X-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).

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 X-PAYMENT 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.

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. The recipient verifies the certificate and calls Core4Mica.remunerate with the certificate bytes and BLS signature.
3. The contract validates domain, timestamp + grace window, tab status, and collateral; it then transfers funds to the recipient.

This path is deterministic: the same certificate that enabled instant delivery becomes the claim that makes the recipient whole.

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 X-PAYMENT.
• 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.