UnFee (unfee.xyz) Developer & AI Agent Documentation

curl -sS -X POST https://unfee.xyz/api/keys/free \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-ai-agent",
    "tier": "free",
    "autoTopUpEnabled": true,
    "alertThresholds": [60, 70, 80, 90, 95]
  }'

{
  "status": "created",
  "verified": true,
  "apiKey": "uf_live_free_9a8f7c6e5d4b3a210987",
  "plan": "free",
  "planName": "$0/mo Starter (5¢ per $1,000 Micro-Fee)",
  "txFeePct": "0.005%",
  "creditsAdded": 250000,
  "creditsRemaining": 250000,
  "maxRps": 10,
  "autoTopUp": {
    "enabled": true,
    "amountUsd": 1,
    "tokensAddedPerTopUp": 2000000,
    "triggerAtUsagePct": 95
  },
  "usageAlerts": {
    "enabled": true,
    "thresholdsPct": [60, 70, 80, 90, 95],
    "statusHeader": "OK (alerts_on:60,70,80,90,95)"
  },
  "create2SplitterAddress": "0xA7a15bCEd59f4B687f5356b880DB3dcDaF086790"
}

<!-- 1-Line Automatic Checkout Button -->
<script
  src="https://unfee.xyz/checkout.js"
  data-merchant="0x04A72616B16Aa4b74A93851eF9FBF7Bf9f2223a8"
  data-merchant-name="Acme Cloud AI"
  data-amount="25.00"
  data-asset="USDC"
  data-item="Pro AI Workflow Subscription (Monthly)"
  data-tier="indie_5"
  data-customer-email="builder@acme.xyz"
  data-webhook-url="https://api.acme.xyz/webhooks/unfee"
></script>

<!-- Or Trigger Programmatically -->
<script>
  UnFeeCheckout.open({
    merchant: "0x04A72616B16Aa4b74A93851eF9FBF7Bf9f2223a8",
    merchantName: "Acme Cloud AI",
    amount: "25.00",
    asset: "USDC",
    item: "Pro AI Workflow Subscription (Monthly)",
    tier: "indie_5",
    customerEmail: "builder@acme.xyz",
    webhookUrl: "https://api.acme.xyz/webhooks/unfee"
  });
</script>

curl -sS -X POST https://unfee.xyz/api/checkout/verify \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "indie_5",
    "asset": "USDC",
    "amountUsdc": "25.00",
    "merchantWallet": "0x04A72616B16Aa4b74A93851eF9FBF7Bf9f2223a8",
    "merchantName": "Acme Cloud AI",
    "item": "Pro AI Workflow Subscription",
    "receiptEmail": "builder@acme.xyz",
    "webhookUrl": "https://api.unfee.xyz/api/webhooks/mock-receiver"
  }'

import { createWalletClient, http, parseUnits } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
import crypto from "node:crypto";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({ account, chain: base, transport: http("https://api.unfee.xyz/rpc/base") });

const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const UNFEE_SPLITTER = "0xA7a15bCEd59f4B687f5356b880DB3dcDaF086790";

async function settleX402AgentKey() {
  const nonce = ("0x" + crypto.randomBytes(32).toString("hex")) as `0x${string}`;
  const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600);
  const value = parseUnits("5.00", 6); // $5.00 Indie Tier -> 10,000,000 credits + 0% fee

  const signature = await client.signTypedData({
    domain: { name: "USD Coin", version: "2", chainId: 8453, verifyingContract: BASE_USDC },
    types: {
      TransferWithAuthorization: [
        { name: "from", type: "address" },
        { name: "to", type: "address" },
        { name: "value", type: "uint256" },
        { name: "validAfter", type: "uint256" },
        { name: "validBefore", type: "uint256" },
        { name: "nonce", type: "bytes32" },
      ],
    },
    primaryType: "TransferWithAuthorization",
    message: { from: account.address, to: UNFEE_SPLITTER, value, validAfter: 0n, validBefore, nonce },
  });

  const res = await fetch("https://unfee.xyz/api/x402/settle", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      plan: "indie_5",
      authorization: {
        from: account.address,
        to: UNFEE_SPLITTER,
        value: value.toString(),
        validAfter: 0,
        validBefore: Number(validBefore),
        nonce,
      },
      signature,
    }),
  });
  console.log("Minted x402 API Key:", await res.json());
}

import os, time, secrets, requests
from eth_account import Account
from eth_account.messages import encode_typed_data

acct = Account.from_key(os.environ["AGENT_PRIVATE_KEY"])
BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
UNFEE_SPLITTER = "0xA7a15bCEd59f4B687f5356b880DB3dcDaF086790"

nonce_hex = "0x" + secrets.token_hex(32)
valid_before = int(time.time()) + 3600
typed_data = {
    "types": {
        "EIP712Domain": [
            {"name": "name", "type": "string"},
            {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"},
            {"name": "verifyingContract", "type": "address"},
        ],
        "TransferWithAuthorization": [
            {"name": "from", "type": "address"},
            {"name": "to", "type": "address"},
            {"name": "value", "type": "uint256"},
            {"name": "validAfter", "type": "uint256"},
            {"name": "validBefore", "type": "uint256"},
            {"name": "nonce", "type": "bytes32"},
        ],
    },
    "domain": {"name": "USD Coin", "version": "2", "chainId": 8453, "verifyingContract": BASE_USDC},
    "primaryType": "TransferWithAuthorization",
    "message": {
        "from": acct.address,
        "to": UNFEE_SPLITTER,
        "value": 5_000_000,
        "validAfter": 0,
        "validBefore": valid_before,
        "nonce": bytes.fromhex(nonce_hex[2:]),
    },
}
signed = Account.sign_message(encode_typed_data(full_message=typed_data), acct.key)
resp = requests.post("https://unfee.xyz/api/x402/settle", json={
    "from": acct.address, "to": UNFEE_SPLITTER, "value": "5000000",
    "plan": "indie_5", "nonce": nonce_hex, "validAfter": 0,
    "validBefore": valid_before, "signature": signed.signature.hex()
})
print(resp.json())

# 1. Base Mainnet (Chain ID 8453) — 1 Call = 1 Credit
curl -sS -X POST https://api.unfee.xyz/rpc/base \
  -H "Content-Type: application/json" \
  -H "X-API-Key: uf_live_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 2. Ethereum Mainnet (Chain ID 1) — 1 Call = 1 Credit
curl -sS -X POST https://api.unfee.xyz/rpc/eth \
  -H "Content-Type: application/json" \
  -H "X-API-Key: uf_live_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 3. Native XRP Ledger (XRPL) — 1 Call = 1 Credit
curl -sS -X POST https://api.unfee.xyz/rpc/xrpl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: uf_live_YOUR_API_KEY" \
  -d '{"method":"server_info","params":[{}]}'

// TypeScript (viem)
import { createPublicClient, http } from "viem";
import { base, mainnet } from "viem/chains";

export const baseClient = createPublicClient({
  chain: base,
  transport: http("https://api.unfee.xyz/rpc/base", {
    fetchOptions: { headers: { "X-API-Key": process.env.UNFEE_API_KEY! } },
  }),
});

// Python (web3.py)
# from web3 import Web3
# w3 = Web3(Web3.HTTPProvider("https://api.unfee.xyz/rpc/base", request_kwargs={"headers": {"X-API-Key": "uf_live_..."}}))
# print(w3.eth.block_number)

import express from "express";
import crypto from "node:crypto";

const app = express();
const WEBHOOK_SECRET = process.env.UNFEE_WEBHOOK_SECRET; // "whsec_unfee_..."

app.post("/webhooks/unfee", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-unfee-signature"] || "";
  const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");
  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).json({ error: "Invalid X-Unfee-Signature" });
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  console.log("Verified UnFee Webhook:", payload.event, payload.txHash);
  res.status(200).json({ received: true });
});

import os, hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = os.environ["UNFEE_WEBHOOK_SECRET"]

@app.post("/webhooks/unfee")
async def verify_unfee_webhook(request: Request):
    raw_body = await request.body()
    sig = request.headers.get("X-Unfee-Signature", "")
    expected = "sha256=" + hmac.new(WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(status_code=401, detail="Invalid X-Unfee-Signature")
    return {"received": True}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface ICreate2FeeSplitter {
    function merchantWallet() external view returns (address);
    function protocolTreasury() external view returns (address);
    function invoiceId() external view returns (bytes32);

    function sweepBaseUSDC() external;
    function sweepToken(address token) external;
    function sweepETH() external;
}