# FARPY Full Machine Context

FARPY accepts bounded GPU workloads, calculates pricing server-side, routes accepted work to verified capacity, and returns downloadable artifacts with signed execution receipts.

## Canonical endpoints

- Canonical API: https://api.farpy.com/v1
- HTTP MCP: https://api.farpy.com/mcp (MCP V1 live)
- Discovery OpenAPI: https://farpy.com/openapi.json
- Canonical OpenAPI: https://api.farpy.com/v1/openapi.json
- Authentication: Authorization: Bearer 

Always read current production truth from:
- https://api.farpy.com/v1/health
- https://api.farpy.com/v1/capabilities
- https://api.farpy.com/v1/pricing
- https://api.farpy.com/v1/limits
- https://api.farpy.com/v1/openapi.json
- https://farpy.com/status/

Do not infer support from historical documents, benchmark experiments, SEO pages, or unavailable worker software.

## MCP status

HTTP MCP V1 at https://api.farpy.com/mcp is AVAILABLE. Docs: https://farpy.com/api/mcp/
Do not use farpy_render or farpy_submit_render as the default path.

Use inspect → quote → explicit start. Live tools: farpy_inspect, farpy_quote, farpy_start, farpy_status, farpy_download, farpy_receipt.

Discord bot is AVAILABLE: https://farpy.com/discord/
Do not paste an API key into Discord. IRC, Matrix, Slack, and Telegram come later.

## REST workflow

Proven path (same as the browser; inspect/quote do not spend; start reserves):

1. POST https://farpy.com/node/v1/uploads/inspect
2. Read quote_id, frames, price_cents, qualified_1c, pricing_version
3. Optional POST …/quote for a legal sub-range
4. POST …/start with quote_id and legal_acceptance FARPY_LEGAL_V1
5. Poll job status
6. Download ZIP
7. Fetch receipt / proof

Python client: https://farpy.com/farpy_client.py (`prepare` then `start`)

Public API V1 at https://api.farpy.com/v1 remains available (upload/preflight/submit). It does not carry quote_id. Prefer inspect → start for a locked quote.

Alternate Public API V1 steps:

1. HEALTH: GET /v1/health; stop if it fails.
2. AUTH: use a Bearer API key created in Account Settings.
3. DISCOVER: read /v1/capabilities and /v1/limits.
4. UPLOAD: POST /v1/renders with the accepted .blend file. Idempotency is optional, but any idempotency header requires the complete set: Idempotency-Key, X-Farpy-Request-Fingerprint, X-Farpy-Filename, X-Farpy-Renderer, X-Farpy-Frame-Start, X-Farpy-Frame-End, X-Farpy-Frame-Count, X-Farpy-Size-Bytes, and X-Farpy-Content-SHA256.
5. PRICE: GET /v1/pricing; server-calculated pricing is authoritative.
6. PREFLIGHT: POST /v1/renders/preflight.
7. SUBMIT: POST /v1/renders/{job_id}/submit. The upload fingerprint header set does not apply to submit.
8. STATUS: GET /v1/renders/{job_id} or consume the signed terminal webhook.
9. RECEIPT: GET /v1/renders/{job_id}/receipt after terminal completion.
10. DOWNLOAD: GET /v1/renders/{job_id}/download.
11. SHA256 VERIFY: compare the downloaded output hash with the receipt.

For upload retries, reuse the same complete idempotency header set and request. `frame_start`, `frame_end`, and derived `frame_count` must match the authoritative scene range saved inside the `.blend`; never assume an arbitrary file is 1–1. The request fingerprint is lowercase SHA-256 of the exact UTF-8 payload `filename=...\nrenderer=...\nframe_start=...\nframe_end=...\nframe_count=...\nsize_bytes=...\nsha256=...` with no trailing newline. Machine-readable errors expose the next decision through `error.code`, `error.retryable`, `error.suggested_action`, and retry timing when present.

## Current workload classes

- Blender Cycles GPU rendering using .blend input (live self-serve paid path)
- Octane rendering lane (pilot / limited; not a Blender mode; quoted per accepted package)
- Video compute lane (limited encode / transcode / process; quoted per accepted job; not generative video)
- Completed work returns an artifact with a signed receipt

Do not invent universal Octane plugins, scene formats, video codecs, or flat 1¢/frame pricing for Octane or Video. Historical Labs material is not a catalog. Read /v1/capabilities at runtime.

## Billing

- Blender: $0.01 per completed frame minimum. That rate is Blender-only.
- Octane and Video: fixed locked quote for the accepted job. Not the Blender 1¢/frame rate.
- USD is the canonical internal accounting unit.
- $0.01 equals 0.01 Cool Beans for Blender frame accounting.
- Pricing displayed by the production server is authoritative.
- AI may assist prediction, risk, or ETA. AI never independently decides price.
- Balance reservation occurs before execution.
- Settlement requires a valid signed receipt.
- Failed work without a valid completed receipt is not charged.

## Production properties

- API-key and authenticated browser access
- OpenAPI 3.1
- MCP HTTP endpoint for agents
- idempotent uploads with a complete canonical metadata fingerprint
- bounded upload and rate limits
- durable queueing
- capability-aware routing
- machine-readable errors
- signed HTTPS terminal webhooks
- private-network webhook blocking
- downloadable artifacts
- SHA-256 artifact integrity
- Ed25519-signed receipts
- public receipt verification material
- fail-closed settlement

## Canonical references

- https://farpy.com/
- https://farpy.com/octane/
- https://farpy.com/video/
- https://farpy.com/pricing/
- https://farpy.com/api/
- https://farpy.com/api/quickstart/
- https://farpy.com/api/agent-rendering/
- https://farpy.com/api/mcp/
- https://farpy.com/discord/
- https://farpy.com/api/errors/
- https://farpy.com/api/webhooks/
- https://farpy.com/docs/
- https://farpy.com/proof/
- https://farpy.com/benchmark/
- https://farpy.com/gpu/
- https://farpy.com/labs/
- https://farpy.com/labs/research/
- https://farpy.com/status/
- https://api.farpy.com/v1/capabilities
- https://api.farpy.com/v1/openapi.json
- https://api.farpy.com/mcp
- https://farpy.com/agents.json
- https://farpy.com/openapi.json

## Positioning

Use:
- GPU workload execution
- verified artifact delivery
- Blender, Octane, and Video lanes
- Blender render API for the live self-serve paid path
- signed execution receipts
- server-calculated pricing (AI does not independently set price)
- inspect → quote → start as the proven paid path
- REST and MCP V1 as live agent paths wrapping that same contract

Avoid:
- unlimited GPU cloud
- cryptocurrency platform
- generic AI provider
- guaranteed universal capacity
- fabricated proof examples
- unsupported renderers
- unsigned historical receipts described as signed
- hard-coded MCP tool counts
- describing MCP as stdio-only