> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ondb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Flows

> Understanding payment options in OnDB

OnDB supports multiple payment flows for different use cases. All payments are made in USDC.

## Payment Methods Overview

| Method                   | Description                              | Best For          |
| ------------------------ | ---------------------------------------- | ----------------- |
| **Payment Callback**     | SDK invokes callback when payment needed | Most applications |
| **Auto-Pay (Agent Key)** | Automatic payments via X-Agent-Key       | Autonomous agents |
| **Pre-paid**             | Payment made before request              | Batch operations  |

## Payment Callback

The recommended approach for most applications. The SDK handles the entire flow automatically:

```typescript theme={null}
const result = await client.store(
  {
    collection: 'posts',
    data: [{ title: 'Hello', content: 'World' }]
  },
  // Payment callback - invoked when server requires payment
  async (quote) => {
    console.log('Payment required:', quote.totalCost);
    console.log('Pay to:', quote.brokerAddress);

    // Execute payment via your wallet
    const txHash = await processPayment(quote);

    return {
      txHash,
      network: quote.network,
      sender: walletAddress,
      chainType: quote.chainType,
      paymentMethod: 'native'
    };
  },
  true // waitForConfirmation
);
```

### Quote Structure

The quote object contains all payment details:

```typescript theme={null}
interface X402Quote {
  quoteId: string;           // Unique quote identifier
  totalCost: number;         // Total cost in USDC
  amountRaw: string;         // Amount in smallest units
  brokerAddress: string;     // Address to pay
  description: string;       // Payment description
  expiresAt: number;         // Quote expiration timestamp
  network: string;           // Network identifier (e.g., "base", "solana")
  asset: string;             // Asset address/identifier
  tokenSymbol: string;       // Token symbol (e.g., "USDC")
  tokenDecimals: number;     // Token decimal places (e.g., 6 for USDC)
  chainType: 'cosmos' | 'evm' | 'solana';
  paymentMethod: 'native' | 'x402-facilitator';
  facilitator?: string;      // Facilitator URL (if applicable)
  allOptions: X402PaymentRequirement[]; // All available payment options
}
```

## Auto-Pay (Agent Key)

When using an Agent Key (an App Key with `Pay` permission), payments are handled automatically by the broker -- no callback needed:

```typescript theme={null}
import { createClient } from '@ondb/sdk';

const agent = createClient({
  endpoint: 'https://api.ondb.io',
  appId: 'my_agent_app',
  agentKey: 'app_a3f9...'  // X-Agent-Key header — key must have Pay permission
});

// No callback needed - payment is automatic
await agent.store({
  collection: 'target_app::data',
  data: [{ content: 'example' }]
});
```

The broker verifies the agent's pay limits, transfers USDC automatically, and completes the write. See [Agent Keys](/concepts/authentication#agent-keys) for configuration and spend limits.

## Pre-paid Transaction

For scenarios where you've already made the payment, pass the payment proof via the callback:

```typescript theme={null}
// Payment was made separately
const paymentTxHash = 'ABC123...';

// Include payment proof via the callback
const result = await client.store(
  { collection: 'data', data: [{ content: 'example' }] },
  async (quote) => ({
    txHash: paymentTxHash,
    network: quote.network,
    sender: walletAddress,
    chainType: quote.chainType,
    paymentMethod: 'native'
  }),
  true
);
```

## Wallet Integration Example

The payment callback is wallet-agnostic. You provide a function that processes the quote and returns a payment result:

```typescript theme={null}
const paymentCallback = async (quote) => {
  // Use any wallet or payment provider to send USDC
  const txHash = await processPayment(quote);

  return {
    txHash,
    network: quote.network,
    sender: walletAddress,
    chainType: quote.chainType,
    paymentMethod: 'native'
  };
};

await client.store(
  { collection: 'data', data: [{ key: 'value' }] },
  paymentCallback,
  true
);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="PriceIndex" icon="tags" href="/payments/price-index">
    Value-based payment model
  </Card>

  <Card title="Paid Reads" icon="book" href="/payments/paid-reads">
    HTTP 402 for read operations
  </Card>
</CardGroup>