Paying with 4Mica

Executive Summary

This guide is for payers and agents who want to consume paid resources using 4Mica credit.

You fund collateral once, receive 402 requirements, sign a payment header (`X-PAYMENT` for v1, `PAYMENT-SIGNATURE` for v2), and later settle the tab on-chain. Recipients get a certificate immediately, so work can be delivered without waiting on chain.

When a route uses V2 guarantees, default-time remuneration is allowed only after the linked ERC-8004 validation request passes (for example using wachai-validation-sdk status checks).

V1 vs V2: What Changes for Payers

V1: sign standard guarantee claims and settle tab on-chain as usual.
V2: sign claims that include validation policy commitments generated from `paymentRequirements.extra`.
Settlement request/response remains the same (`/verify`, `/settle`), but V2 certificates are validation-gated only when default remuneration is attempted.
Both versions stay available; payers do not lose V1 compatibility.

Switching from x402 Debit to 4Mica Credit

If a resource migrates from an x402 debit facilitator to the 4Mica credit facilitator, the flow changes from immediate on-chain payment to credit-backed guarantees.

Expect `paymentRequirements.scheme = "4mica-credit"` (or another scheme containing "4mica") plus `extra.tabEndpoint` in the 402 response.
If the endpoint enforces V2, expect validation fields in `paymentRequirements.extra`: `validationRegistryAddress`, `validatorAddress`, `validatorAgentId`, `minValidationScore`, and `validationChainId` (optional `requiredValidationTag`). `validationChainId` must match `network` (`eip155:<chainId>`).
Deposit collateral before your first credit request; the facilitator refuses tabs for empty balances.
Use the 4Mica SDK X402Flow to sign the guarantee and produce the payment header (`X-PAYMENT` for v1, `PAYMENT-SIGNATURE` for v2).
Retry the request with the payment header, then pay the tab later using the `req_id` from the certificate.
Keep your old debit path as a fallback if the scheme is not 4mica.

What You Need

A wallet private key with collateral available (ETH or ERC20).
The recipient endpoint you want to call.
Access to a 4Mica network: Ethereum Sepolia (https://ethereum.sepolia.api.4mica.xyz/) or Base Sepolia (https://base.sepolia.api.4mica.xyz/).
A 402 response that advertises `scheme: "4mica-credit"` and `extra.tabEndpoint`.

Step 1: Fund Collateral (Payer SDK)

Credit requires collateral in the Core4Mica vault. Deposit once per asset and reuse the same collateral for multiple tabs.

For ERC20 assets, approve first, then deposit.

Deposit collateral (TypeScript SDK)

1import { Client, ConfigBuilder } from "@4mica/sdk";

2

3const cfg = new ConfigBuilder()

4 .network(process.env["4MICA_NETWORK"] ?? "base-sepolia")

5 .walletPrivateKey(process.env.PAYER_KEY!)

6 .build();

7

8const client = await Client.new(cfg);

9

10// ETH deposit

11await client.user.deposit(10_000n);

12

13// ERC20 flow (approve then deposit)

14// const token = "0xTokenAddress";

15// await client.user.approveErc20(token, 1_000_000n);

16// await client.user.deposit(1_000_000n, token);

17

18await client.aclose();

Step 2: Parse 402 Requirements & Select 4Mica Credit

Make the request without payment to receive a 402 response. Then parse the requirements and ensure the scheme is 4mica credit.

For V2 accepted payloads, verify the required validation fields are present in `requirements.extra` before signing.

Parse requirements (TypeScript SDK)

1import { PaymentRequirements } from "@4mica/sdk";

2

3const requirements = PaymentRequirements.fromRaw(reqRaw); // from 402 response

4if (!requirements.scheme.includes("4mica")) {

5 throw new Error("Unsupported scheme; expected 4mica credit.");

6}

Step 3: Sign the Payment Header (Payer SDK)

Use the SDK to build and sign the payment guarantee. The SDK automatically calls the tabEndpoint to refresh the tab and returns a base64 payment header.

If the V2 validation fields are present, SDKs sign V2 claims and compute canonical `validationSubjectHash` + `validationRequestHash`; otherwise they sign V1.

Sign payment header (TypeScript SDK)

1import { Client, ConfigBuilder, X402Flow } from "@4mica/sdk";

2

3const cfg = new ConfigBuilder()

4 .network(process.env["4MICA_NETWORK"] ?? "base-sepolia")

5 .walletPrivateKey(process.env.PAYER_KEY!)

6 .build();

7

8const client = await Client.new(cfg);

9const flow = X402Flow.fromClient(client);

10

11// requirements from Step 2

12const payment = await flow.signPayment(requirements, "0xUserAddress");

13const xPaymentHeader = payment.header;

14

15await client.aclose();

Step 4: Retry the Request with the Payment Header

Retry the same request with the payment header. The recipient will call /verify and /settle and then serve the response.

For V2 flows, `/settle` returns a certificate that carries validation policy fields; it does not by itself prove the job result.

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

After receiving the response, settle the tab on-chain using the req_id in the certificate.

This unlocks collateral and keeps your account healthy for future requests.

Pay the tab (TypeScript SDK)

1const receipt = await client.user.payTab(

2 tabId,

3 reqId, // from certificate

4 amountWei,

5 recipientAddress,

6 undefined // or ERC20 token address

7);

Optional: Settle via the Facilitator (SDK helper)

If a recipient delegates settlement to the payer (less common), you can call the facilitator /settle endpoint using the SDK.

Settle with the facilitator (TypeScript SDK)

1const settled = await flow.settlePayment(

2 payment,

3 requirements,

4 "https://x402.4mica.xyz"

5);

6

7const certificate = settled.settlement;

Handle 402 Responses in Client Code

Call the resource and check for HTTP 402.
Parse paymentRequirements and confirm the scheme is 4mica credit (fallback to debit if not).
Sign the payment header with the SDK (it calls tabEndpoint internally).
Retry the request with that header.
If 402 returns again, surface the error and refresh the tab.

Operational Tips

Track tab TTL and settle before expiry (default 21 days) to avoid remuneration.
If unpaid, recipients can remunerate after the grace period (default 14 days). For V2, this only succeeds after matching ERC-8004 validation status exists on-chain.
Always use the req_id from the certificate, not a cached value.
Reuse collateral across tabs, but monitor balances if you issue many guarantees.
If you rotate keys, create fresh tabs to avoid mismatched user addresses.

Why This Works

Credit lets you access services instantly while keeping settlement on-chain and enforceable. The certificate is the cryptographic bridge between off-chain delivery and on-chain repayment, and V2 adds validation-gated remuneration for “pay only if validated” integrations.