{ "openapi": "3.1.0", "info": { "title": "FreelanceDesk - USDC checkout for agents", "version": "1.2.16", "description": "Invoicing and billing resources sold per call to software. POST invoice JSON to check it (0.05 USD), get a print-ready A4 invoice as PDF (0.10 USD) or as self-contained HTML (0.10 USD), or GET the FreelanceDesk app and document pack as zip downloads. Each endpoint answers 402 with two payment options: an x402 v2 PAYMENT-REQUIRED challenge and an MPP WWW-Authenticate challenge (method evm, intent charge). Both settle an exact USDC EIP-3009 transfer on Base (eip155:8453) and return the resource in the same response.", "x-guidance": "Four paid POST routes and two paid GET routes, each answering 402 with two rails. POST /v1/invoice/preflight (0.01 USD) takes invoice JSON and returns only the blocking errors plus net, tax and total; POST /v1/invoice/validate (0.05 USD) returns a JSON report of every finding (severity, code, JSON path, message) plus server-computed totals; POST /v1/invoice/pdf (0.10 USD) takes invoice JSON and returns an A4 PDF; POST /v1/invoice/render (0.10 USD) takes the same JSON and returns self-contained A4 HTML. The POST routes accept the invoice as a JSON body or, for clients that cannot send bodies, URL-encoded in the ?json= query parameter. Totals are computed server-side with integer cents. GET /freelancedesk (14.00 USD) and GET /documents (7.00 USD) return zip downloads. Pay in USDC on Base. Rail A (x402 v2): read PAYMENT-REQUIRED, sign the exact EIP-3009 authorization, resend it in PAYMENT-SIGNATURE. Rail B (MPP): read WWW-Authenticate, pay with any MPP client (method evm), resend the credential in Authorization: Payment. No account, key or signup. Success returns the resource plus a receipt header (PAYMENT-RESPONSE for x402, Payment-Receipt for MPP)." }, "servers": [ { "url": "https://afraid-butterfly-5236.obtranzat.deno.net" } ], "paths": { "/freelancedesk": { "get": { "operationId": "buy_freelancedesk", "summary": "Buy FreelanceDesk Pro 1.1.1 - FreelanceDesk-1.1.1.zip", "description": "Offline single-file invoicing and client tracker for freelancers. One HTML file you keep, no account, no subscription, works with no internet.", "tags": [ "x402" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "14.00" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "Zip archive: FreelanceDesk-1.1.1.zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "Payment Required" } } } }, "/documents": { "get": { "operationId": "buy_documents", "summary": "Buy Freelance Document Pack 1.1.0 - Freelance-Documents-1.1.0.zip", "description": "Editable contract, statement of work, NDA, welcome pack and invoice templates for independent professionals.", "tags": [ "x402" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "7.00" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "Zip archive: Freelance-Documents-1.1.0.zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "Payment Required" } } } }, "/health": { "get": { "operationId": "health", "summary": "Free health check", "security": [], "responses": { "200": { "description": "ok", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/invoice/render": { "post": { "operationId": "render_invoice", "summary": "Render a print-ready A4 invoice as HTML", "description": "Renders a print-ready A4 invoice as self-contained HTML from structured JSON: seller, buyer, invoice number and dates, line items with per-line tax rates, currency. Line nets, tax breakdown and total are computed server-side with integer cents.", "tags": [ "invoicing" ], "parameters": [ { "name": "json", "in": "query", "required": false, "description": "Alternative to the JSON body for clients that can only append a query string: the same invoice object, URL-encoded. Ignored when a body is sent.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "seller", "client", "number", "date", "items" ], "properties": { "seller": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "client": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "number": { "type": "string", "description": "Invoice number, e.g. 2026-014" }, "date": { "type": "string", "description": "Issue date, YYYY-MM-DD" }, "dueDate": { "type": "string", "description": "Due date, YYYY-MM-DD" }, "currency": { "type": "string", "description": "ISO 4217 code, default EUR" }, "taxMode": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "default exclusive" }, "taxLabel": { "type": "string", "description": "default VAT" }, "notes": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "description", "quantity", "unitPrice" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "type": "string", "description": "Non-negative amount, max 2 decimals" }, "taxRate": { "type": "number", "minimum": 0, "maximum": 100 } } } } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "Self-contained A4 HTML invoice; X-Invoice-Total carries the total in major units", "content": { "text/html": { "schema": { "type": "string" } } } }, "402": { "description": "Payment Required" }, "422": { "description": "Body is valid JSON but cannot be rendered (no payment taken)" } } } }, "/v1/invoice/pdf": { "post": { "operationId": "render_invoice_pdf", "summary": "Render a print-ready A4 invoice as PDF", "description": "Renders a print-ready A4 PDF invoice (PDF 1.4, Helvetica) from the same structured JSON: seller, buyer, invoice number and dates, line items with per-line tax rates, currency. Line nets, tax breakdown and total are computed server-side with integer cents.", "tags": [ "invoicing" ], "parameters": [ { "name": "json", "in": "query", "required": false, "description": "Alternative to the JSON body for clients that can only append a query string: the same invoice object, URL-encoded. Ignored when a body is sent.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "seller", "client", "number", "date", "items" ], "properties": { "seller": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "client": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "number": { "type": "string", "description": "Invoice number, e.g. 2026-014" }, "date": { "type": "string", "description": "Issue date, YYYY-MM-DD" }, "dueDate": { "type": "string", "description": "Due date, YYYY-MM-DD" }, "currency": { "type": "string", "description": "ISO 4217 code, default EUR" }, "taxMode": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "default exclusive" }, "taxLabel": { "type": "string", "description": "default VAT" }, "notes": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "description", "quantity", "unitPrice" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "type": "string", "description": "Non-negative amount, max 2 decimals" }, "taxRate": { "type": "number", "minimum": 0, "maximum": 100 } } } } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "A4 PDF (PDF 1.4); X-Invoice-Total carries the total in major units", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "Payment Required" }, "422": { "description": "Body is valid JSON but cannot be rendered (no payment taken)" } } } }, "/v1/invoice/validate": { "post": { "operationId": "validate_invoice", "summary": "Check invoice JSON and report every finding", "description": "Checks invoice JSON before it is sent or paid: required parties and number, currency and date formats, due date order, line item ranges, per-line tax rates, duplicate lines and VAT-ID shape. Returns every finding with severity and a JSON path, plus server-computed net, tax and total totals.", "tags": [ "invoicing" ], "parameters": [ { "name": "json", "in": "query", "required": false, "description": "Alternative to the JSON body for clients that can only append a query string: the same invoice object, URL-encoded. Ignored when a body is sent.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "seller", "client", "number", "date", "items" ], "properties": { "seller": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "client": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "number": { "type": "string", "description": "Invoice number, e.g. 2026-014" }, "date": { "type": "string", "description": "Issue date, YYYY-MM-DD" }, "dueDate": { "type": "string", "description": "Due date, YYYY-MM-DD" }, "currency": { "type": "string", "description": "ISO 4217 code, default EUR" }, "taxMode": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "default exclusive" }, "taxLabel": { "type": "string", "description": "default VAT" }, "notes": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "description", "quantity", "unitPrice" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "type": "string", "description": "Non-negative amount, max 2 decimals" }, "taxRate": { "type": "number", "minimum": 0, "maximum": 100 } } } } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "Validation report: valid flag, findings with severity/path, and computed totals. X-Invoice-Valid mirrors the flag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "number": { "type": "string" }, "currency": { "type": "string" }, "totals": { "type": [ "object", "null" ], "properties": { "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "severity", "code", "path", "message" ] } } }, "required": [ "valid", "findings" ] } } } }, "402": { "description": "Payment Required" }, "422": { "description": "Body is valid JSON but cannot be rendered (no payment taken)" } } } }, "/v1/invoice/preflight": { "post": { "operationId": "preflight_invoice", "summary": "Validate invoice JSON, compute tax and total (blocking errors only)", "description": "Validates invoice JSON and computes net, tax and total, returning only the blocking errors that would stop a send or a payment. The cheap door to the five-cent full report, which adds every warning and info finding with a JSON path.", "tags": [ "invoicing" ], "parameters": [ { "name": "json", "in": "query", "required": false, "description": "Alternative to the JSON body for clients that can only append a query string: the same invoice object, URL-encoded. Ignored when a body is sent.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "seller", "client", "number", "date", "items" ], "properties": { "seller": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "client": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "vatId": { "type": "string" } } }, "number": { "type": "string", "description": "Invoice number, e.g. 2026-014" }, "date": { "type": "string", "description": "Issue date, YYYY-MM-DD" }, "dueDate": { "type": "string", "description": "Due date, YYYY-MM-DD" }, "currency": { "type": "string", "description": "ISO 4217 code, default EUR" }, "taxMode": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "default exclusive" }, "taxLabel": { "type": "string", "description": "default VAT" }, "notes": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "description", "quantity", "unitPrice" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "type": "string", "description": "Non-negative amount, max 2 decimals" }, "taxRate": { "type": "number", "minimum": 0, "maximum": 100 } } } } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "evm", "intent": "charge", "currency": "USDC" } } ] }, "responses": { "200": { "description": "Preflight result: valid flag, blocking errors only, and computed totals. X-Invoice-Valid mirrors the flag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "number": { "type": "string" }, "currency": { "type": "string" }, "totals": { "type": [ "object", "null" ], "properties": { "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error" ] }, "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "severity", "code", "path", "message" ] } } }, "required": [ "valid", "errors" ] } } } }, "402": { "description": "Payment Required" }, "422": { "description": "Body is valid JSON but cannot be rendered (no payment taken)" } } } } } }