# Parrot Payments — Complete Technical Specification (llms-full.txt)
Version: 1.0.0
Base URL: https://parrotpay.com
Protocol: Solana USDC Native Payment Gateway (Humans + AI Agents)
Fee Rate: 0.05% (5 basis points)
Settlement: Non-custodial, direct wallet-to-wallet

---

## 1. Executive Overview
Parrot Payments is a decentralized, non-custodial payment infrastructure for digital software businesses and autonomous agent networks. Merchants accept USDC on Solana directly into their own wallets. 

Key differentiators:
1. Universal Dual-Rail: One payment gateway serves both interactive human browser checkouts (Phantom, Solflare, Backpack) and headless autonomous AI agents (programmatic keypair signing).
2. True Micropayments: 0.05% platform fee with zero fixed base fees (eliminating Stripe's $0.30–$0.50 fixed penalty). Viable down to $0.01 per transaction.
3. Cryptographic Verification: Non-custodial. Payout wallets are verified using Ed25519 signature proof of ownership. Transactions embed a random 32-byte reference public key on-chain for verification.

---

## 2. Supported Networks & Mint Addresses
Never trust arbitrary token symbols. The mint addresses are hardcoded:
- Solana Mainnet USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
- Solana Devnet USDC: `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`
- Decimals: 6 (1 USDC = 1,000,000 raw units; $0.10 = 100,000 raw units)

---

## 3. Merchant API Reference

### 3.1 Authentication
Pass merchant secret keys in standard Authorization header:
```
Authorization: Bearer sk_test_... (or sk_live_...)
Idempotency-Key: <unique-order-uuid>
```

### 3.2 Create Payment Session
`POST /api/v1/payments`
Headers:
- `Authorization: Bearer <API_KEY>`
- `Idempotency-Key: <UUID>`
- `Content-Type: application/json`

Request Body:
```json
{
  "amount": 100000,
  "customer": "cust_agent_42",
  "customer_email": "agent@autonomous.org",
  "success_url": "https://mysaas.com/success",
  "metadata": {
    "query": "vector_search",
    "compute_units": 450
  }
}
```

Response (HTTP 201 Created / HTTP 200 Replayed):
```json
{
  "id": "c3f8d876-0000-4000-8000-0123456789ab",
  "object": "payment",
  "status": "created",
  "amount": "100000",
  "fee_amount": "50",
  "currency": "USDC",
  "mode": "live",
  "tx_signature": null,
  "payer_address": null,
  "customer": "cust_agent_42",
  "metadata": { "query": "vector_search" },
  "created_at": "2026-10-24T00:00:00Z",
  "checkout_url": "https://parrotpay.com/checkout/c3f8d876-0000-4000-8000-0123456789ab"
}
```

### 3.3 Retrieve Payment
`GET /api/v1/payments?id=<payment_id>`
Headers:
- `Authorization: Bearer <API_KEY>`

---

## 4. Public Hosted & Agent Checkout API

### 4.1 Build Transaction
`POST /api/checkout/:id`
Content-Type: application/json

Request Body:
```json
{
  "action": "build",
  "account": "<Payer_Solana_Public_Key_Base58>"
}
```

Response (HTTP 200 OK):
```json
{
  "transaction": "<Base64_Serialized_Solana_Transaction>"
}
```

### 4.2 Confirm Transaction
`POST /api/checkout/:id`
Content-Type: application/json

Request Body:
```json
{
  "action": "confirm",
  "signature": "<Solana_Transaction_Signature_Base58>"
}
```

Response (HTTP 200 OK):
```json
{
  "status": "succeeded",
  "success_url": "https://mysaas.com/success"
}
```

---

## 5. Autonomous AI Agent Implementation Guide

### 5.1 The HTTP 402 Flow
When an AI agent accesses a paywalled SaaS route:
1. SaaS endpoint responds with `HTTP 402 Payment Required`:
```json
{
  "error": "payment_required",
  "payment_id": "c3f8d876-...",
  "amount_usd": 0.05,
  "checkout_url": "https://parrotpay.com/checkout/c3f8d876-..."
}
```
2. Agent reads `payment_id`, builds transaction via `/api/checkout/:id`, signs with its local keypair, broadcasts to Solana, and calls `confirm`.
3. Agent retries original SaaS request with `X-Payment-Signature: <signature>`.

### 5.2 Standalone Agent Payer Script (Node.js)
```typescript
import { Keypair, Transaction, Connection } from '@solana/web3.js';
import bs58 from 'bs58';

async function executeAgentPayment(paymentId: string, agentPrivateKeyBase58: string) {
  const agentKeypair = Keypair.fromSecretKey(bs58.decode(agentPrivateKeyBase58));
  const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed');

  // Step 1: Request atomic transaction
  const buildRes = await fetch(`https://parrotpay.com/api/checkout/${paymentId}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ action: 'build', account: agentKeypair.publicKey.toBase58() })
  });
  const { transaction: txBase64 } = await buildRes.json();

  // Step 2: Sign transaction in-memory
  const tx = Transaction.from(Buffer.from(txBase64, 'base64'));
  tx.partialSign(agentKeypair);

  // Step 3: Broadcast directly to Solana
  const signature = await connection.sendRawTransaction(tx.serialize());
  await connection.confirmTransaction(signature, 'confirmed');

  // Step 4: Settle with Parrot
  await fetch(`https://parrotpay.com/api/checkout/${paymentId}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ action: 'confirm', signature })
  });

  return signature;
}
```

---

## 6. On-Chain Atomic Transaction Structure
Every Parrot transaction is constructed atomically:
1. `createAssociatedTokenAccountIdempotent`: Merchant's USDC ATA (payer covers rent if unallocated).
2. `transferChecked`: Transfers `(amount - fee)` USDC to merchant ATA. Embedded read-only `reference` key for indexing.
3. `createAssociatedTokenAccountIdempotent`: Treasury's USDC ATA.
4. `transferChecked`: Transfers `fee` USDC (0.05%) to treasury ATA.

---

## 7. Webhook Verification (HMAC-SHA256)
Webhooks are signed using HMAC-SHA256:
- Header: `x-signature: t=<timestamp>,v1=<hex_signature>`
- Payload Signed: `${timestamp}.${raw_json_body}`

Verification in Node.js:
```typescript
import crypto from 'crypto';

function verifyWebhook(body: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
```