# Subpay

> Subpay reads construction pay applications (AIA G702/G703, Procore, Textura) and change orders from PDF into structured JSON, with arithmetic checks. Pay-per-read API for AI agents: $0.20 in USDC per successful read over x402 on Base or Solana. No account, no API key. Failed reads are not charged. Documents are read and discarded, never stored.

## API

- Endpoint: POST https://subpay.ai/api/v1/extract
- Free service description: GET https://subpay.ai/api/v1/extract
- OpenAPI spec: https://subpay.ai/openapi.json
- MCP server (Streamable HTTP): https://subpay.ai/mcp — tools: extract_document (paid, same price; PDF base64 in "document"), about (free). Payment per tool call over x402 (@x402/mcp); failed calls are not charged.
- Payment: x402 protocol, scheme "exact", USDC. Networks: Base (eip155:8453) and Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). The first request returns HTTP 402 with the price and receiving address; an x402 client pays and retries. The payer needs only USDC; the facilitator pays network fees.
- Price: $0.20 per read with HTTP status below 400. Errors (400, 413, 415, 502, 503) are not charged.

## Request

Send the PDF (max 4 MB) in one of three forms:
- Raw PDF body, Content-Type: application/pdf
- multipart/form-data with the PDF in field "file"
- JSON: {"document": "<base64 PDF>", "fileName": "optional", "subcontractor": "optional company name", "gc": "optional general contractor name"}

Naming the subcontractor and gc (JSON fields, or query parameters otherwise) improves telling a subcontractor's request for change order from the general contractor's executed change order.

## Response

JSON with "document", "checks", "warnings", "confidence".
- Pay application: documentType "PAY_APPLICATION", applicationNumber, periodTo, grossThisPeriod, retainageHeldToDate, retainageReleasedThisPeriod, retainageRatePercent, totalCompletedAndStoredToDate, contractSumToDate, balanceToFinishIncludingRetainage, currentPaymentDue, changeOrders[].
- Change order: documentType "CHANGE_ORDER", kind ("SUBCONTRACTOR_REQUEST" or "GC_CHANGE_ORDER"), issuer, number, description, amount, date.
- checks: g702_math (contract sum − completed [+ retainage] = balance to finish), first_application_gross, retainage_billing. A failed check also appears in warnings.
- Retainage billing (no new work, held retainage paid out): grossThisPeriod is 0 and the payout is retainageReleasedThisPeriod.
- Figures not printed on the document are null. Output is automated: verify against the document before relying on it.

## Docs

- [Developer documentation](https://subpay.ai/developers): request forms, response examples, errors, limits
- [API Terms of Use](https://subpay.ai/api-terms): sending a request or payment means accepting these terms
- [Privacy Policy](https://subpay.ai/privacy)

## Optional

- Subpay is also a web app for construction subcontractors to track pay applications, change orders, and retainage. That app requires an account and is not part of the API.
- Support: support@subpay.ai