# IPFS Pay-to-Pin Gateway — Agent Reference

An HTTP API that gates file storage (pinning) on IPFS using standard x402 microUSDC micropayments on Algorand. Each payment provides 365 days of pinning retention.

## Endpoints

1. `POST /api/v1/pin`
   - Request Body: JSON `{ "filename": "example.txt", "data": "<base64_string>" }`
   - Response: `402 Payment Required` header `PAYMENT-REQUIRED` (microUSDC pricing based on file size).
   - Resubmit: Send exact same POST request with `PAYMENT-SIGNATURE` header containing signed transaction.
   - Output (201 Created): Returns `cid`, `ipfs_cid`, `gateway_url`, `pinned_at`, `expires_at` (+365 days), and `renewal_url`.

2. `POST /api/v1/renew`
   - Request Body: JSON `{ "cid": "<ipfs_cid>" }`
   - Response: `402 Payment Required` header `PAYMENT-REQUIRED` (Includes a 50% early renewal discount if renewed before expiration).
   - Output (200 OK): Extends retention period by another 365 days and updates `expires_at`.

3. `GET /api/v1/pin/:cid`
   - Free status lookup endpoint (no payment required).
   - Output (200 OK): Returns `pinned_at`, `expires_at`, `days_remaining`, and `is_active`.

OpenAPI specification available at `/openapi.json`.