Skip to main content

​
Configuration

@4mica/sdk needs a signing key and can use sensible defaults for everything else. Build a Config with ConfigBuilder, then pass it to Client.new.

​
Options

OptionRequiredDescription
walletPrivateKeyYes, unless signer is providedPrivate key used for signing.
signerYes, unless walletPrivateKeyA pre-built viem Account. Mutually exclusive with walletPrivateKey.
networkNoNetwork shorthand or CAIP-2 id. Defaults to ethereum-sepolia.
rpcUrlNoOverride the core API URL directly (for self-hosted deployments).
ethereumHttpRpcUrlNoEthereum JSON-RPC endpoint. Fetched from core when omitted.
contractAddressNoCore4Mica contract address. Fetched from core when omitted.
adminApiKeyNoAPI key for admin RPCs.
bearerTokenNoStatic bearer token for auth. Disables SIWE auth.
authUrlNoSIWE auth endpoint. Defaults to rpcUrl when auth is enabled.
authRefreshMarginSecsNoSeconds before expiry at which the session refreshes. Defaults to 60.
ethereumHttpRpcUrl and contractAddress are fetched from the core service by default. The SDK validates the connected chain id but does not verify the contract address or code. Only override these if you need values that differ from the server defaults.

​
Using ConfigBuilder

ConfigBuilder is a fluent builder. Chain the options you need, then call build(). 
import { Client, ConfigBuilder } from "@4mica/sdk";

const cfg = new ConfigBuilder()
  .network("base") // or "ethereum-sepolia" (default)
  .walletPrivateKey("0x...")
  .build();

const client = await Client.new(cfg);
build() throws a ConfigError when a signer or wallet key is missing, a URL is invalid, or the auth refresh margin is not a finite non-negative number.

​
Using environment variables

Call fromEnv() to load configuration from the environment. 
4MICA_WALLET_PRIVATE_KEY="0x..."
4MICA_NETWORK="base"                   # shorthand or CAIP-2 id
# or override the URL directly:
# 4MICA_RPC_URL="https://base.sepolia.api.4mica.xyz/"
4MICA_ETHEREUM_HTTP_RPC_URL="http://localhost:8545"
4MICA_CONTRACT_ADDRESS="0x..."
4MICA_ADMIN_API_KEY="ak_..."
4MICA_BEARER_TOKEN="Bearer <access_token>"
4MICA_AUTH_URL="https://ethereum.sepolia.api.4mica.xyz/"
4MICA_AUTH_REFRESH_MARGIN_SECS="60"

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

const cfg = new ConfigBuilder().fromEnv().build();
const client = await Client.new(cfg);
Most shells do not allow variable names that start with a digit. To set them inline for a single command, use env: env 4MICA_WALLET_PRIVATE_KEY="0x..." 4MICA_NETWORK="base" node app.js.

​
Using a custom signer

To integrate a hardware wallet, remote signer, or MPC wallet, pass a viem Account. It must expose address, signTypedData, and signMessage. 
import { Client, ConfigBuilder } from "@4mica/sdk";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
const cfg = new ConfigBuilder().signer(signer).build();
const client = await Client.new(cfg);

​
Coinbase CDP wallet

Use createCdpAccount for a Coinbase CDP MPC wallet whose private key never leaves CDP. It returns a viem Account you can pass to .signer(). This requires the optional @coinbase/cdp-sdk dependency. 
import { Client, ConfigBuilder, createCdpAccount } from "@4mica/sdk";

const signer = await createCdpAccount({
  apiKeyId: process.env.CDP_API_KEY_ID!,
  apiKeySecret: process.env.CDP_API_KEY_SECRET!,
  walletSecret: process.env.CDP_WALLET_SECRET!,
  name: "my-agent-wallet", // idempotent — the same name returns the same wallet
});

const cfg = new ConfigBuilder().network("base-sepolia").signer(signer).build();
const client = await Client.new(cfg);

​
SIWE authentication

Auth is enabled by default. Enable automatic SIWE refresh, or pass a static bearer token. 
import { Client, ConfigBuilder } from "@4mica/sdk";

const cfg = new ConfigBuilder()
  .walletPrivateKey("0x...")
  .rpcUrl("https://api.4mica.xyz/")
  .enableAuth()
  .build();

const client = await Client.new(cfg);
await client.login(); // optional: the first RPC call also triggers auth
Or use a static token instead of SIWE: 
const cfg = new ConfigBuilder()
  .walletPrivateKey("0x...")
  .bearerToken("Bearer <access_token>")
  .build();
Never commit private keys. Use a test wallet while you develop and a dedicated service wallet, hardware-backed signer, MPC wallet, or hosted key management system in production.
Start on Base Sepolia (eip155:84532) with small amounts. Once a flow works end to end, move shared values into environment variables and switch networks.

​
Next steps

Overview

Install the SDK and see the capabilities at a glance.

Client operations

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