Documentation

Drip uses ERC-4337 smart accounts (DripAccount) for customer fund management. Unlike traditional custodial solutions, users maintain control of their own funds.

• Users deposit USDC into their own smart account
• Funds remain in the user's control until charged
• Account abstraction enables gasless transactions for users
• Compatible with existing EOA wallets via counterfactual deployment

Session keys provide scoped, time-limited permissions for billing operations. They allow Drip to charge customers without requiring user signatures for each transaction.

• Target scoping: Keys can only call specific contract addresses
• Selector scoping: Keys are limited to specific function selectors
• Time bounds: Keys expire after a configurable duration (e.g., 30 days)
• Rate limits: maxPerCall and maxPerPeriod caps prevent excessive charges
• Revocable: Users can revoke session keys at any time

The BillingModule smart contract handles USDC custody and charge execution. It enforces all billing invariants on-chain.

• Deposits: Users deposit USDC into their billing balance
• Withdrawals: Users can withdraw available balance at any time
• Charges: Authorized charges deduct from user balance
• Events: All operations emit events for auditability

Every usage event generates a unique usageId that prevents double-charging. This is enforced both off-chain and on-chain.

• Each charge transaction includes the usageId
• The BillingModule rejects duplicate usageIds
• Use idempotencyKey for client-side deduplication
• Charges can be queried and reconciled by usageId

Drip includes a circuit breaker that pauses billing operations if USDC depegs significantly from its $1 target. This protects both merchants and customers from unexpected value loss.

• 5% threshold: Billing pauses if USDC/USD price deviates more than 5%
• Chainlink oracle: Price feeds from decentralized oracles
• Automatic resume: Operations resume when price stabilizes
• Manual override: Operators can pause/unpause if needed

Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

curl -X GET https://api.drip.dev/v1/customers \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Creating Customers

Before charging a user, create a customer record linking their identity to their on-chain address.

interface CreateCustomerRequest {
  externalCustomerId?: string;  // Your internal user ID
  onchainAddress: string;       // 0x... Ethereum address
  metadata?: Record<string, any>;
}

// Example
const customer = await fetch('/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalCustomerId: 'user_123',
    onchainAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
    metadata: { plan: 'pro', signupDate: '2024-01-15' }
  })
});

Recording Usage Events

Record usage events as they occur. Each event triggers a charge based on your pricing configuration.

interface RecordUsageRequest {
  customerId: string;      // Drip customer ID
  usageType: string;       // e.g., "api_call", "compute_minute"
  quantity: number;        // Must be positive
  idempotencyKey?: string; // Client-generated, max 64 chars
  metadata?: Record<string, any>;
}

// Synchronous charging (waits for on-chain confirmation)
const result = await fetch('/v1/usage', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customerId: 'cus_abc123',
    usageType: 'api_call',
    quantity: 100,
    idempotencyKey: 'req_' + Date.now()
  })
});

// Async charging (returns immediately, use webhooks for confirmation)
const asyncResult = await fetch('/v1/usage/async', {
  method: 'POST',
  // ... same body
});

Handling Webhooks

Subscribe to webhooks for real-time notifications about charges, balances, and other events.

// Register a webhook
await fetch('/v1/webhooks', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/drip',
    events: ['charge.succeeded', 'charge.failed', 'customer.balance.low']
  })
});

// Verify webhook signature (HMAC-SHA256)
const crypto = require('crypto');
const signature = req.headers['x-drip-signature'];
const expectedSig = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const isValid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expectedSig)
);

Error Handling

The API returns standard HTTP status codes and structured error responses.

Trust-Minimized Architecture

Drip is designed to minimize trust requirements. Users maintain control of their funds at all times, and billing operations are constrained by on-chain logic.

Rate Limits & Caps

Multiple layers of rate limiting protect against runaway charges.

How x402 Works

Response Headers (402)

When a 402 Payment Required is returned, these headers contain payment details:

HTTP/1.1 402 Payment Required
X-Payment-Required: true
X-Payment-Amount: 0.001000
X-Payment-Currency: USDC
X-Payment-Recipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f...
X-Payment-Chain: base-sepolia
X-Payment-Description: Usage charge: api_call
X-Payment-Usage-Id: 550e8400-e29b-41d4-a716-446655440000
X-Payment-Expires: 1703001234567

Payment Proof Headers

After signing, include these headers when retrying the request:

POST /v1/usage HTTP/1.1
Authorization: Bearer sk_live_...
X-Payment-Signature: 0x1234...abcd
X-Payment-Session-Key: sk_session_123
X-Payment-Smart-Account: 0x742d35Cc6634C0532925a3b844Bc9e7595f...
X-Payment-Timestamp: 1703001234567

Signing Endpoint

Use the signing endpoint to create a payment signature:

// POST /v1/x402/sign
const response = await fetch('/v1/x402/sign', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    smartAccount: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
    sessionKeyId: 'sk_session_123',
    paymentRequest: {
      amount: '0.001000',
      recipient: '0x...',
      usageId: '550e8400-e29b-41d4-a716-446655440000',
      expiresAt: 1703001234567
    }
  })
});

const { signature, timestamp } = await response.json();

What chains does Drip support?

Drip is deployed on Base L2 (mainnet) and Base Sepolia (testnet). Base provides low transaction fees and fast confirmation times, making it ideal for metered billing.

What happens if a user runs out of funds?

When a user's balance is too low for a charge, the API returns a 402 Payment Required error. You can subscribe to the customer.balance.low webhook to proactively notify users before this happens.

How are gas fees handled?

Users pay gas fees for deposits and withdrawals. For charges, Drip batches transactions and covers gas fees, passing a small portion to merchants as part of the settlement fee.

Can users revoke session keys?

Yes. Users can revoke session keys at any time through the dashboard or by calling the smart contract directly. Revoked keys immediately lose the ability to authorize charges.

Is there a minimum charge amount?

There is no minimum charge amount enforced by Drip. However, for very small charges, batching is recommended to optimize gas efficiency.