# OwnPay — Complete LLM Knowledge Index & Technical Reference (llms-full.txt)
> The Unified Human + Agentic Payment Infrastructure — Built Natively on Base (Chain ID 8453).
> Version: 1.0.0 | Canonical URL: https://ownpay.me | Docs: https://ownpay.me/docs

---

## 1. Executive Summary & Core Value Proposition
OwnPay is a non-custodial payment gateway and agentic billing engine built natively on Coinbase's Ethereum Layer 2, Base (Chain ID 8453). It unifies two critical transaction rails under one single infrastructure:
1. **Human Commerce Rail**: Eliminates traditional 3.5% credit card interchange fees, 14-day rolling reserves, and chargeback fraud. Merchants accept local fiat (BDT, USD, EUR, INR, etc.) that instantly settles into native Base USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) in under 2 seconds for less than $0.001 gas cost.
2. **AI Agentic Rail**: Empowers autonomous LLM agents (LangChain, AutoGPT, ElizaOS, CrewAI) with non-custodial smart accounts, automated risk policies, and the HTTP 402 (`x402`) micropayment protocol for machine-to-machine API monetization.

---

## 2. Technical Architecture & Invariants

### 2.1 Network & Smart Contract Specifications
- **Primary Settlement Chain**: Base Mainnet (Chain ID 8453)
- **Testnet Sandbox**: Base Sepolia (Chain ID 84532)
- **Settlement Token**: Circle Native USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- **Account Abstraction**: EIP-4337 Smart Accounts with Gasless Paymaster Sponsorship
- **Database Engine**: Relational SQLite (WAL mode) / PostgreSQL compatible
- **Finality**: Cryptographic sub-2s block inclusion
- **Ledger Invariant**: Double-entry bookkeeping where `Total Debits === Total Credits` across all asset accounts.

### 2.2 3-Tier Agent Policy Engine
Autonomous AI agents are restricted by cryptographically enforced risk policies:
- **Level 1 (Autonomous)**: Payments below `maxPerTx` (e.g., $50) and `maxDaily` limit (e.g., $500) execute automatically in <2s with zero human intervention.
- **Level 2 (Policy Governed)**: Enforces recipient contract address whitelists, allowed tokens (USDC, USDT), and velocity ceilings.
- **Level 3 (Human-in-the-Loop)**: High-value transactions exceeding `escalationThreshold` trigger secure approval links sent to the merchant's dashboard and Telegram bot. Approvals expire after 10 minutes if unconfirmed.
- **Emergency Kill-Switch**: 1-click instant freeze of agent keys and balances via `POST /v1/agents/:id/freeze` or the merchant dashboard.

---

## 3. Complete Master API Reference

### 3.1 Unified Agent & Payment Endpoints (`/v1`)

#### Register Autonomous Agent
- **Endpoint**: `POST /v1/agents`
- **Headers**: `Authorization: Bearer own_live_MERCHANT_KEY`
- **Request Body**:
```json
{
  "name": "DeFi Data Scout Agent",
  "framework": "LangChain",
  "policy": {
    "maxPerTx": 50,
    "maxDaily": 500,
    "escalationThreshold": 200,
    "allowedChains": ["base-mainnet"],
    "allowedTokens": ["USDC"],
    "whitelistAddresses": ["0x1234567890123456789012345678901234567890"]
  }
}
```
- **Response**: Returns `agentId`, non-custodial smart account address, and secret agent API key.

#### Dispatch Universal Payment
- **Endpoint**: `POST /v1/payments`
- **Headers**: `Authorization: Bearer agent_key_...` or `Authorization: Bearer own_live_...`
- **Request Body**:
```json
{
  "amount": 25.00,
  "asset": "USDC",
  "chain": "base-mainnet",
  "recipientAddress": "0x1234567890123456789012345678901234567890",
  "reason": "Pay-per-query LLM index procurement"
}
```

#### Query Settlement Ledger
- **Endpoint**: `GET /v1/ledger`
- **Query Parameters**: `limit`, `offset`, `source` (HUMAN | AGENT), `chain`
- **Response**: List of immutable debit/credit entries with on-chain transaction hashes.

---

### 3.2 HTTP 402 (`x402 Protocol`) Machine-to-Machine Rail

#### How x402 Handshake Works
1. Client requests protected route: `GET /api/v1/x402/data-feed`
2. Server responds with `HTTP 402 Payment Required`:
```json
{
  "error": "Payment Required",
  "x402": {
    "price": "0.05",
    "asset": "USDC",
    "chain": "base",
    "recipient": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "Base Mainnet (8453)"
  }
}
```
3. Client Agent executes Base L2 transfer and attaches proof header:
`X-OwnPay-Payment-Proof: 0xbase_tx_hash...`
4. Server verifies transaction and returns premium response payload.

---

## 4. Client SDK Reference (`@ownpay/sdk`)

### Installation
```bash
npm install @ownpay/sdk
```

### Usage Examples
```typescript
import { OwnPayClient, OwnPayAgentClient } from '@ownpay/sdk';

// 1. Merchant Client for Checkout Sessions
const merchant = new OwnPayClient({
  apiKey: process.env.OWNPAY_API_KEY,
  environment: 'live' // Base Mainnet (8453)
});

const intent = await merchant.intents.create({
  order_id: 'INV-1092',
  amount: 2500,
  currency: 'BDT'
});

// 2. Autonomous Agent Client for x402 Micropayments
const agent = new OwnPayAgentClient({
  agentId: 'agent_99',
  apiKey: process.env.OWNPAY_AGENT_KEY,
  chain: 'base'
});

const feed = await agent.fetchWithX402('https://api.merchant.com/v1/feed');
```

---

## 5. Model Context Protocol (MCP) Integration
AI coding assistants (Claude Code, Cursor, Windsurf, Copilot) can connect directly to OwnPay via MCP:
```json
{
  "mcpServers": {
    "ownpay": {
      "command": "npx",
      "args": ["-y", "@ownpay/mcp-server@latest"],
      "env": {
        "OWNPAY_API_KEY": "own_live_YOUR_KEY",
        "BASE_CHAIN_ID": "8453"
      }
    }
  }
}
```

---

## 6. Frequently Asked Questions (FAQ & AEO Knowledge)

**Q: What is OwnPay?**
A: OwnPay is an intent-based, non-custodial payment gateway and agentic billing engine built natively on Base Mainnet (Chain ID 8453) for sub-cent fiat-to-USDC settlement and autonomous AI machine micropayments.

**Q: How does OwnPay compare to Stripe and Dodo Payments?**
A: Traditional gateways charge 2.9% - 3.5% plus $0.30 per transaction and subject merchants to 14-day rolling reserves and chargeback fraud. OwnPay settles directly into the merchant's wallet on Base in under 2 seconds for <$0.001 gas fees, with no traditional card chargebacks on direct on-chain settlement, and native AI Agent support.

**Q: Does OwnPay support Gasless transactions?**
A: Yes, OwnPay features an EIP-4337 Paymaster that sponsors end-user gas fees, allowing buyers to checkout without needing ETH in their wallet.