# payable.link — Full Agent Documentation

> Sell any file with crypto. Upload, set a USDC price, share a link.

## Platform Overview

payable.link enables sellers to upload digital files (up to 1 GB), set prices in USDC, and share purchase links. Buyers pay with USDC on Base (Ethereum L2) and receive instant download access. The platform charges a flat 3% commission per sale.

- No KYC or identity verification required
- Wallet-based authentication (SIWE)
- Instant settlement — seller receives funds in the same transaction
- All payments in USDC (stablecoin, 1 USDC = 1 USD)
- USDC contract on Base mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Base chain ID: 8453 (CAIP-2: eip155:8453)

## x402 Payment Protocol

payable.link implements the x402 protocol for native HTTP payments.

### Purchase Flow

1. Agent sends GET to `https://payable.link/f/{slug}`
2. Server responds with HTTP 402 (Payment Required)
   - Response includes `X-Payment` header with payment requirements:
     - Price in USDC (6 decimals)
     - Recipient address (PaymentSplitter contract)
     - Network (eip155:8453 for Base mainnet)
     - USDC token address
3. Agent constructs a USDC transfer on Base to the specified recipient
4. Agent signs and submits the transaction on-chain
5. Agent retries the original GET request with the `X-Payment-Response` header containing the payment proof
6. Server verifies payment via the CDP facilitator
7. Server returns the file via presigned R2 download URL (HTTP 307 redirect)

### Response Codes

- 200 — File delivered (via 307 redirect to presigned URL)
- 402 — Payment required (includes payment details in headers)
- 404 — File not found
- 410 — File no longer available (inactive/suspended)
- 500 — Server error

## EIP-191 Re-download Protocol

After purchasing, agents can re-download files by proving wallet ownership.

### Endpoint

GET `https://payable.link/api/f/{slug}/agent-download`

### Authentication

Authorization header format:
```
Authorization: Bearer eip191:<base64(address:timestamp:signature)>
```

Signed message format:
```
payable.link:download:{slug}:{timestamp}
```

- Timestamp: Unix seconds, must be within 5 minutes of server time
- Signature: EIP-191 personal_sign of the message above

### Response Codes

- 307 — Redirect to presigned download URL
- 401 — Invalid or expired signature
- 402 — No purchase found (use x402 flow to buy)
- 403 — Access denied (download limit reached or access expired)
- 404 — File not found

## EIP-191 Agent Upload Protocol

Agents can upload files programmatically without a browser session.

### Account Provisioning

If the wallet has no existing payable.link account, the server auto-creates
the user/account/wallet records on the first successful authenticated upload
request. Browser SIWE registration is not required for agent uploads.

### Endpoint

POST `https://payable.link/api/upload`

Content-Type: `multipart/form-data`

### Authentication

Same EIP-191 scheme as the re-download protocol, with an upload-specific signed message.

Authorization header format:
```
Authorization: Bearer eip191:<base64(address:timestamp:signature)>
```

Signed message format:
```
payable.link:upload:{timestamp}
```

- Timestamp: Unix seconds, must be within 5 minutes of server time
- Signature: EIP-191 personal_sign of the message above

### Required Fields

| Field   | Type   | Description                                      |
|---------|--------|--------------------------------------------------|
| `file`  | binary | The file to upload (multipart file field)         |
| `price` | string | Sale price in USDC (up to 6 decimal places)       |

### Constraints

- Maximum file size for agent uploads: 100 MB (browser uploads support larger files via presigned URLs)
- Minimum price: configurable (default $0.10 USDC)
- USDC precision: up to 6 decimal places
- Blocked MIME types: text/html, text/xml, application/xhtml+xml, image/svg+xml, text/javascript, application/javascript, application/x-msdownload, application/x-executable, application/x-sharedlib

### Success Response

```json
{
  "slug": "aBcDe12345",
  "url": "https://payable.link/f/aBcDe12345"
}
```

### Response Codes

- 200 — File uploaded and listed successfully
- 400 — Validation error (missing fields, invalid price, blocked MIME type, empty file)
- 401 — Invalid/expired signature
- 413 — File exceeds agent upload size limit
- 500 — Server error

### Error Response Shape

```json
{
  "error": "Human-readable error message",
  "code": "machine_readable_code"
}
```

Error codes: `auth_error`, `validation_error`, `blocked_mime_type`, `file_too_large`, `content_too_large`, `internal_error`

### Example: curl

```bash
# 1. Build the signed message
TIMESTAMP=$(date +%s)
MESSAGE="payable.link:upload:${TIMESTAMP}"

# 2. Sign with your wallet (using cast from Foundry as example)
SIGNATURE=$(cast wallet sign --private-key $PRIVATE_KEY "$MESSAGE")

# 3. Build the auth header
TOKEN=$(echo -n "${ADDRESS}:${TIMESTAMP}:${SIGNATURE}" | base64)

# 4. Upload
curl -X POST https://payable.link/api/upload \
  -H "Authorization: Bearer eip191:${TOKEN}" \
  -F "file=@./my-document.pdf" \
  -F "price=5.00"
```

### Notes

- The slug in the response URL is the public identifier for the file listing
- Buyers can purchase the file at the returned URL via x402 or browser
- The 3% platform commission is applied automatically on each sale
- File constraints (maxPurchases, availableUntil, etc.) are set to defaults; use the dashboard to customize

## File Constraints

Sellers can configure per-file constraints:

- `maxPurchases` — Maximum number of total purchases allowed (null = unlimited)
- `availableUntil` — Datetime after which the file can no longer be purchased (null = no expiry)
- `buyerMaxDownloads` — Maximum downloads per buyer (null = unlimited)
- `buyerAccessHours` — Hours after purchase that download access expires (null = no expiry)

## Error Handling

Common error scenarios:

- File suspended: Returns 410. File was removed for policy violation.
- File inactive: Returns 410. Seller deactivated the listing.
- Purchase limit reached: Returns 403 with `downloadCount` and `maxDownloads`.
- Access expired: Returns 403 with `expiresAt` timestamp.
- Sold out: Returns 402 but the file cannot accept new purchases.

## Links

- Website: https://payable.link
- Terms: https://payable.link/terms
- Privacy: https://payable.link/privacy
- DMCA: https://payable.link/dmca
- Contact: contact@payable.link
- Summary: https://payable.link/llms.txt