Skip to main content

​
TypeScript SDK

@4mica/sdk is the official TypeScript SDK for the 4Mica payment network. Use it to deposit collateral, sign payment guarantees, verify and settle them, run the x402 HTTP flow, and gate your own routes behind a payment. The SDK exposes five capabilities:
  • User client (client.user) — deposit collateral, sign payments, and manage withdrawals in ETH or ERC20 tokens.
  • Recipient client (client.recipient) — issue and verify payment guarantees, and claim net credit from cleared settlement cycles.
  • X402 flow helper (X402Flow) — turn a 402 Payment Required response into a signed payment header.
  • Server paywall (@4mica/sdk/server) — an edge-safe primitive that gates a route behind an x402 payment.
  • Admin RPCs (client.rpc) — manage user suspension and admin API keys when authorized.

​
Runtime-neutral

@4mica/sdk runs on Node, Bun, Deno, and edge runtimes. HTTP uses the global fetch, and the @4mica/sdk/server subpath is Buffer-free so it runs on the edge.
Prefer a runtime or framework adapter for idiomatic wiring: @4mica/sdk-node, @4mica/sdk-bun, and @4mica/sdk-deno for env-driven client and paywall factories, and @4mica/sdk-next, @4mica/sdk-express, and @4mica/sdk-hono for thin x402 middleware.

​
Install

Node.js 18 or later is required. 
npm install @4mica/sdk

pnpm install @4mica/sdk

yarn add @4mica/sdk

bun add @4mica/sdk

​
Networks

The default network is Ethereum Sepolia. Select a network with .network() or the 4MICA_NETWORK environment variable.
ShorthandCAIP-2Core API URL
baseeip155:8453https://base.api.4mica.xyz/
base-sepoliaeip155:84532https://base.sepolia.api.4mica.xyz/
ethereum-sepoliaeip155:11155111https://ethereum.sepolia.api.4mica.xyz/
Read network details from the exported NETWORKS constant: 
import { NETWORKS } from "@4mica/sdk";

console.log(NETWORKS.base.caip2); // "eip155:8453"
console.log(NETWORKS.base.rpcUrl); // "https://base.api.4mica.xyz/"

​
Your first client

Build a config, create a Client, and always close it when you are done. Start on Base Sepolia (eip155:84532) with a test wallet. 
import { Client, ConfigBuilder } from "@4mica/sdk";

const cfg = new ConfigBuilder()
  .network("base-sepolia") // or "ethereum-sepolia" (default)
  .walletPrivateKey(process.env.PRIVATE_KEY as `0x${string}`)
  .build();

const client = await Client.new(cfg);
try {
  // use client.user, client.recipient, and client.rpc
} finally {
  await client.aclose();
}
Client.new connects to the core service, fetches public parameters, and wires up the on-chain gateway. From the client you reach the three entry points:
  • client.user — payer-side operations (collateral, signing, withdrawals, net-debit settlement).
  • client.recipient — recipient-side operations (guarantees, net-credit settlement).
  • X402Flow — the helper for 402-protected HTTP resources.
Keep private keys in environment variables instead of committing them to your code. Use a dedicated test wallet while you develop.

​
Next steps

Configuration

Initialize a client with ConfigBuilder, environment variables, or a custom signer.

Client operations

Deposit collateral, sign payments, issue guarantees, and settle cleared cycles.

X402 flow

Turn a 402 Payment Required response into a signed payment header.

Server paywall

Gate any route behind an x402 payment with the edge-safe primitive.