# PFOF Exchange

> PFOF is a wallet-bound route API for same-chain and cross-chain swaps. Developer access is invite-only.

Canonical site: https://pfof.exchange
Developer guide: https://pfof.exchange/developers
OpenAPI 3.1: https://pfof.exchange/api/v1/openapi.json
Support: dracula@pfof.exchange

## Integration rules

- The API is server-to-server. Never expose a PFOF API key in browser JavaScript, mobile binaries, public repositories, logs, analytics, URLs, or screenshots.
- Authenticate with `Authorization: Bearer pfof_live_...`.
- Discover supported chain IDs with `GET /api/v1/chains`.
- Discover token addresses and decimals with `GET /api/v1/tokens?chainId={id}`.
- Request live routes with `POST /api/v1/quote`. Amounts are integer strings in token base units. Slippage is in basis points.
- The native token address on supported EVM chains is `0x0000000000000000000000000000000000000000`.
- A quote is bound to `walletAddress`. Do not substitute another sender.
- Never cache executable routes. Respect `expiresAt` and request a fresh quote after expiry.
- If `route.approval.transaction` exists, the user must submit and confirm it before the route transaction.
- Submit the returned transaction `chainId`, `target`, `data`, and `value` unchanged for wallet review and signing.
- After the route transaction confirms, send its `routeId` and `transactionHash` to `POST /api/v1/settlements` from the server.
- PFOF verifies the chain, sender, target, calldata, value, receipt status, and replay status before attributing an execution.
- Honor `Retry-After`, `X-RateLimit-*`, and `X-Quota-Monthly-*` response headers. Do not retry 4xx validation errors without changing the request.
- Treat transaction calldata and quote responses as short-lived execution material, not proof that a swap has settled.

## API surface

- `GET /api/v1/health` — unauthenticated service health.
- `GET /api/v1/chains` — authenticated supported-chain catalog.
- `GET /api/v1/tokens` — authenticated token catalog and search.
- `POST /api/v1/quote` — authenticated best executable route.
- `POST /api/v1/settlements` — authenticated execution verification and attribution.
- `GET /api/v1/earnings` — authenticated execution-verified partner earnings pending reconciliation.

## Partner payouts

- Partner earnings are calculated only from executions verified through `POST /api/v1/settlements` and remain pending until PFOF reconciles the underlying provider revenue.
- To register a payout wallet, email `dracula@pfof.exchange` with the partner/project ID, EVM payout address, preferred payout chain, preferred payout asset, and operational contact email.
- PFOF will reply with a one-time verification message. Sign that exact message with the proposed payout wallet and return the signature. Do not send a seed phrase, private key, API key, or wallet-export file.
- Smart-contract wallets must provide an EIP-1271-compatible signature or coordinate an equivalent ownership check with PFOF.
- Payout-wallet changes repeat the same verification process. API credentials cannot change payout destinations.
- During private beta, verified earnings are reconciled and paid on the agreed schedule to the registered wallet. `GET /api/v1/earnings` is an accounting ledger, not an on-chain claim endpoint.
- The `earnings` totals and `settlementCount` cover the durable all-time verified ledger. The `settlements` array contains only the latest 100 records; use it for recent reconciliation, not for recomputing the all-time total.

## Safety

PFOF returns transaction requests; it does not hold partner keys or user signing keys. Users must review and sign transactions in their own wallets. Applications should independently display token, amount, chain, destination, minimum output, and approval details before requesting a signature.