Billing & Agents

Plans & Pricing

Epitome offers three ways to access the platform: a free tier for getting started, a Pro subscription for power users, and agent pay-per-call for AI agents that need pro-tier access without a subscription.

Upgrading to Pro

Upgrading to Pro takes less than a minute and immediately unlocks unlimited resources.

1. Navigate to the Billing page in the dashboard
2. Click "Upgrade to Pro"
3. Complete checkout via Stripe
4. Your account is immediately upgraded — no restart required

Managing Your Subscription

All subscription management is handled through the Stripe customer portal.

• Access the Stripe customer portal from the Billing page in the dashboard
• Cancel anytime — access continues until end of billing period
• On cancellation, account reverts to free tier
• Existing data is preserved but new resource creation may be blocked if over free limits

Tier Limits & Enforcement

Limits are enforced atomically at time of resource creation. When you hit a limit, the API returns HTTP 402 with an error explaining which limit was reached.

Free Tier Limits

• 2 tables — custom user-created tables
• 3 agents — registered API key agents
• 100 graph entities — nodes in the knowledge graph
• 30 days — audit log retention

Pro Tier Limits

• Unlimited tables, agents, and graph entities
• 365 days — audit log retention

Agent Pay-Per-Call (x402)

The x402 protocol enables AI agents to pay for individual API calls using cryptocurrency. When an agent on the free tier calls an MCP tool, Epitome responds with HTTP 402 Payment Required, including payment details in the response. The agent can then pay with USDC on Base and retry the request with proof of payment, receiving pro-tier access for that call.

Payment Flow

Agent calls MCP tool
  → Epitome checks tier
  → If free tier: returns HTTP 402 with payment details
    → Payment details include: price, currency, network, pay-to address
  → Agent pays with USDC on Base
  → Agent retries request with payment proof (X-Payment header)
  → Epitome verifies payment on-chain
  → Request processed with pro-tier access

Supported Networks

Base SepoliaTestnet for development and testing.

BaseMainnet for production use.

Pricing

$0.01 per MCP tool call (USDC). No subscription needed — each call is independent.

Self-Hosting Configuration

To enable x402 agent pay-per-call on your self-hosted instance, set the following environment variables:

X402_ENABLED=true
X402_PAY_TO_ADDRESS=0xYourAddress
X402_PRICE_PER_CALL=0.01
X402_NETWORK=eip155:84532            # Base Sepolia testnet (alias: "base-sepolia")
# X402_NETWORK=eip155:8453           # Base mainnet (alias: "base")
# X402_FACILITATOR_URL=              # Auto-selected: x402.org (testnet) or CDP (mainnet)
# CDP_API_KEY_ID=                    # Required for mainnet CDP facilitator
# CDP_API_KEY_SECRET=                # Required for mainnet CDP facilitator

Billing API Endpoints

All billing endpoints require session authentication. Agent API keys cannot access billing endpoints.

GET /v1/billing/usage

Returns current tier, limits, and usage counts for your account.

curl -s https://epitome.fyi/v1/billing/usage \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

# Response:
# {
#   "tier": "free",
#   "limits": { "max_tables": 2, "max_agents": 3, "max_graph_entities": 100 },
#   "usage": { "tables": 1, "agents": 2, "graph_entities": 47 }
# }

GET /v1/billing/subscription

Returns Stripe subscription details for Pro users, or null for free tier accounts.

curl -s https://epitome.fyi/v1/billing/subscription \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

# Response:
# {
#   "subscription": {
#     "status": "active",
#     "current_period_end": "2026-03-18T00:00:00Z",
#     "cancel_at_period_end": false
#   }
# }

POST /v1/billing/checkout

Creates a Stripe checkout session and returns a URL to redirect the user to.

curl -s -X POST https://epitome.fyi/v1/billing/checkout \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

# Response:
# { "url": "https://checkout.stripe.com/c/pay/cs_live_..." }

POST /v1/billing/portal

Creates a Stripe customer portal session for managing subscription and payment methods.

curl -s -X POST https://epitome.fyi/v1/billing/portal \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

# Response:
# { "url": "https://billing.stripe.com/p/session/..." }

GET /v1/billing/transactions

Returns x402 transaction history for your account, including payment amounts, transaction hashes, and which MCP tools were called.

curl -s https://epitome.fyi/v1/billing/transactions \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

# Response:
# {
#   "transactions": [
#     {
#       "id": "txn_abc123",
#       "tool": "memorize",
#       "amount": "0.01",
#       "currency": "USDC",
#       "network": "base",
#       "tx_hash": "0x...",
#       "created_at": "2026-02-18T12:00:00Z"
#     }
#   ]
# }

FAQ

What happens when I hit a free tier limit?

The API returns HTTP 402 with details on which limit was reached. Upgrade to Pro or use x402 pay-per-call to continue.

Can I downgrade from Pro?

Yes, cancel your subscription from the Stripe customer portal. Access continues until the end of your current billing period. After that, your account reverts to the free tier.

Are x402 payments refundable?

No, x402 payments are non-refundable blockchain micro-transactions. Each payment is settled on-chain and cannot be reversed.

What if I'm self-hosting?

Self-hosted instances have no billing by default. All limits are configurable via environment variables. See the Self-Hosting Guide for details on configuring tier limits and x402.