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 an X-PAYMENT header, and later settle the tab on-chain. Recipients get a certificate immediately, so work can be delivered without waiting on chain.
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.
- 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 `X-PAYMENT` header.
- Retry the request with `X-PAYMENT`, 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 the 4Mica operator API (default: https://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 "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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();
1import { Client, ConfigBuilder } from "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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();
1import { Client, ConfigBuilder } from "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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.
Parse requirements (TypeScript SDK)
1import { PaymentRequirements } from "sdk-4mica";
2
3const requirements = PaymentRequirements.fromRaw(reqRaw); // from 402 response
4if (!requirements.scheme.includes("4mica")) {
5 throw new Error("Unsupported scheme; expected 4mica credit.");
6}
1import { PaymentRequirements } from "sdk-4mica";
2
3const requirements = PaymentRequirements.fromRaw(reqRaw); // from 402 response
4if (!requirements.scheme.includes("4mica")) {
5 throw new Error("Unsupported scheme; expected 4mica credit.");
6}
1import { PaymentRequirements } from "sdk-4mica";
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 X-PAYMENT (Payer SDK)
Use the SDK to build and sign the payment guarantee. The SDK automatically calls the tabEndpoint to refresh the tab and returns the base64 X-PAYMENT header.
Sign X-PAYMENT (TypeScript SDK)
1import { Client, ConfigBuilder, X402Flow } from "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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();
1import { Client, ConfigBuilder, X402Flow } from "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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();
1import { Client, ConfigBuilder, X402Flow } from "sdk-4mica";
2
3const cfg = new ConfigBuilder()
4 .rpcUrl(process.env["4MICA_RPC_URL"] ?? "https://api.4mica.xyz/")
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 X-PAYMENT
Retry the same request with the X-PAYMENT header. The recipient will call /verify and /settle and then serve the response.
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);
1const receipt = await client.user.payTab(
2 tabId,
3 reqId, // from certificate
4 amountWei,
5 recipientAddress,
6 undefined // or ERC20 token address
7);
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;
1const settled = await flow.settlePayment(
2 payment,
3 requirements,
4 "https://x402.4mica.xyz"
5);
6
7const certificate = settled.settlement;
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 X-PAYMENT with the SDK (it calls tabEndpoint internally).
- Retry the request with X-PAYMENT.
- 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).
- 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.