{
  "openapi": "3.1.0",
  "info": {
    "title": "audit.domains machine resolve",
    "version": "1.4.0",
    "description": "The keyless lane for software that cannot hold an API key. One endpoint, /api/machine/resolve. GET returns the live terms, including which payment lanes are open right now (payments.card.status and payments.x402.status). The card lane is a $5 Square checkout: no account, no sign-in, and a person opens the checkout link to pay. The prepaid balance lane is for a funded agent with no person in the loop: a signed-in human operator loads a balance and grants the agent an expiring limit at https://audit.domains/machine-account, then the agent POSTs action purchase (version purchase-1, operationId, grantId, domain, intent, maxSpendUsd) and recovers with purchase_status; new purchases are available only when GET reports settlement.balance and recoverablePurchases.purchaseOpen true, and only for settlement.sellable products. recoverablePurchases.enabled describes receipt recovery, which can remain available when new sales close. When no payment lane can deliver the requested operator-account product, its quote returns 503 product_unavailable with availableProducts and no purchase action. Independent card or x402 offers remain available when their own lane can deliver. The x402 lane is closed unless GET reports payments.x402.status open. The keyed API (ad_live_ keys, https://audit.domains/api/openapi.json) is the other paid route and is not needed here. Names with a published figure are free at https://audit.domains/domain/{name}/index.json and are refused on the card lane with 409 free_in_catalog. An authenticated agent can inspect only its own existing grants using action agent_status, version agent-status-1. This read-only, private snapshot shows exact scopes, expiry, residual credit capacity and remaining attempts without creating authority. Download https://audit.domains/agent-planner.mjs with agent-purchase-plan.mjs and agent-buyer.mjs for dependency-free Node 22 preflight; planning never reserves credits or executes a purchase."
  },
  "servers": [
    {
      "url": "https://audit.domains"
    }
  ],
  "paths": {
    "/api/machine/resolve": {
      "get": {
        "summary": "Live terms: products, open payment lanes and how to pay",
        "operationId": "machineTerms",
        "responses": {
          "200": {
            "description": "Terms document. Read payments.card.status, payments.x402.status, and settlement.balance. Funded new sales also require recoverablePurchases.purchaseOpen and a product in settlement.sellable; recoverablePurchases.enabled alone only confirms that receipt recovery is available.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "tags": ["machine"]
      },
      "post": {
        "summary": "Buy with an existing funded grant, recover a purchase, use card checkout, or pay by enrolled card",
        "description": "For unattended purchases, use Authorization: Bearer ad_agent_<token> and action purchase with version purchase-1, a persisted operationId, an existing operator-issued grantId, domain, intent and explicit maxSpendUsd. The route enforces grant scope, expiry, balance and spending limits. Persist the original arguments before sending. Recover with purchase_status; a pending delivery resumes only by retrying purchase with the SAME operationId and original arguments after retryAfterSeconds. Never increase the ceiling or choose a new identifier for recovery. For card_checkout, a person pays at the returned Square checkoutUrl; keep orderId and secret orderToken and poll card_status. Card credentials are shown once. card_checkout is idempotent on operationId: repeating it with the same domain and intent returns the same orderId with no checkoutUrl (status checkout_exists), never a second payable order; a repeat that changes the domain or intent is operation_id_conflict (409), and the orderToken is shown only at the first checkout for an operationId. A paid card order that cannot be delivered is refunded. For agent card purchases, use action card_agent_pay with version card-agent-1, a persisted operationId, an existing grantId, an enrolled cardRef, domain, intent and explicit maxSpendUsd. The cardholder enrolls the card once, in person, at /api/machine/card-enroll; after enrollment no person and no checkout page is involved. Repeat the identical card_agent_pay request with the same operationId to recover any uncertain outcome; it never charges twice. Recover state at any time with card_agent_status and the operationId alone. Without an action, a free intent answers 200. A supported paid intent answers 402 with the available offer; when no lane can deliver the requested operator-account product, its quote answers 503 product_unavailable, availableProducts and no purchase action. Existing purchase and purchase_status requests can recover their original receipts even when new sales close. Live GET terms are authoritative about available payment lanes and products. For read-only authority discovery, send action agent_status with version agent-status-1 and the agent bearer, with no caller identity fields. A snapshot is advisory and non-reserving; capacity can change before purchase. Truncated snapshots must not be used for automatic grant selection. The planner intersects an explicit buyer cap, authoritative free quote and exact grant scope, choosing the least authority deterministically. It never replaces an existing operation journal.",
        "operationId": "machineResolve",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/AgentStatus"
                  },
                  {
                    "$ref": "#/components/schemas/AgentPurchase"
                  },
                  {
                    "$ref": "#/components/schemas/AgentPurchaseStatus"
                  },
                  {
                    "$ref": "#/components/schemas/CardCheckout"
                  },
                  {
                    "$ref": "#/components/schemas/CardStatus"
                  },
                  {
                    "$ref": "#/components/schemas/CardAgentPay"
                  },
                  {
                    "$ref": "#/components/schemas/CardAgentStatus"
                  },
                  {
                    "$ref": "#/components/schemas/Resolve"
                  }
                ]
              },
              "examples": {
                "quote": {
                  "summary": "Step 0 of the canonical recipe fresh-appraisal-purchase-1: quote only. No action field; a paid intent answers 402 with the offer and never charges.",
                  "value": {
                    "domain": "example.com",
                    "intent": "appraise",
                    "maxSpendUsd": 0.03
                  }
                },
                "checkout": {
                  "value": {
                    "action": "card_checkout",
                    "domain": "example.com",
                    "intent": "appraise",
                    "operationId": "my-order-0001"
                  }
                },
                "status": {
                  "value": {
                    "action": "card_status",
                    "orderId": "<orderId from card_checkout>",
                    "orderToken": "<64 hex characters from card_checkout>"
                  }
                },
                "cardAgentPay": {
                  "value": {
                    "action": "card_agent_pay",
                    "version": "card-agent-1",
                    "operationId": "my-card-purchase-0001",
                    "grantId": "33333333-3333-4333-8333-333333333333",
                    "cardRef": "acr_0123456789abcdef0123456789abcdef",
                    "domain": "example.com",
                    "intent": "appraise",
                    "maxSpendUsd": 5
                  }
                },
                "cardAgentStatus": {
                  "value": {
                    "action": "card_agent_status",
                    "version": "card-agent-1",
                    "operationId": "my-card-purchase-0001"
                  }
                },
                "purchase": {
                  "summary": "Step 1 of the canonical recipe fresh-appraisal-purchase-1: the only step that moves money. Step 2 is purchaseStatus with the same operationId.",
                  "value": {
                    "action": "purchase",
                    "version": "purchase-1",
                    "operationId": "my-purchase-0001",
                    "grantId": "33333333-3333-4333-8333-333333333333",
                    "domain": "example.com",
                    "intent": "appraise",
                    "maxSpendUsd": 0.03
                  }
                },
                "purchaseStatus": {
                  "value": {
                    "action": "purchase_status",
                    "version": "purchase-1",
                    "operationId": "my-purchase-0001"
                  }
                },
                "agentAuthority": {
                  "value": {
                    "action": "agent_status",
                    "version": "agent-status-1"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A fulfilled funded-purchase receipt, a card checkout link, a delivered card appraisal, or a free result. Or a private advisory agent-status-1 snapshot of the authenticated agent's own grants.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Pending funded purchase, awaiting card payment, or delivery in progress. Respect retryAfterSeconds or Retry-After. Status reads do not resume a funded purchase; retry its original purchase request with the same operationId."
          },
          "400": {
            "description": "Invalid request, such as operation_id_invalid, domain_and_intent_required or order_token_required."
          },
          "402": {
            "description": "Paid offer, insufficient prepaid balance, or insufficient scoped grant budget. No automatic funding or ceiling increase."
          },
          "404": {
            "description": "Unknown purchase operation, unknown card order or wrong card token, or endpoint disabled."
          },
          "409": {
            "description": "A refunded funded-purchase receipt restores service credits to the account. Operation conflict refuses changes to an existing funded request. Card free_in_catalog returns the published figureUrl."
          },
          "429": {
            "description": "rate_limited. Retry later."
          },
          "503": {
            "description": "Purchase authority, payment lane, product or engine unavailable. An uncertain purchase outcome must be recovered using the original operationId; do not assume no credits were charged."
          },
          "401": {
            "description": "Funded purchase requires a valid expiring ad_agent_ bearer."
          },
          "403": {
            "description": "Authenticated agent lacks the required scoped grant authority, or its grant is expired or revoked."
          }
        },
        "tags": ["machine"],
        "security": [
          {},
          {
            "AgentBearer": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "CardCheckout": {
        "type": "object",
        "required": ["action", "domain", "operationId"],
        "properties": {
          "action": {
            "const": "card_checkout"
          },
          "domain": {
            "type": "string",
            "examples": ["example.com"]
          },
          "intent": {
            "type": "string",
            "default": "appraise"
          },
          "operationId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{8,128}$",
            "description": "A label you choose for this order."
          }
        }
      },
      "CardStatus": {
        "type": "object",
        "required": ["action", "orderId", "orderToken"],
        "properties": {
          "action": {
            "const": "card_status"
          },
          "orderId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{8,64}$"
          },
          "orderToken": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "CardAgentPay": {
        "type": "object",
        "required": [
          "action",
          "version",
          "operationId",
          "grantId",
          "cardRef",
          "domain",
          "maxSpendUsd"
        ],
        "properties": {
          "action": {
            "const": "card_agent_pay"
          },
          "version": {
            "const": "card-agent-1"
          },
          "operationId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{8,128}$",
            "description": "Your idempotency key for this charge. Persist it before sending; repeat the identical request to recover any uncertain outcome."
          },
          "grantId": {
            "type": "string",
            "format": "uuid",
            "description": "An operator-issued grant naming product current_appraisal."
          },
          "cardRef": {
            "type": "string",
            "pattern": "^acr_[0-9a-f]{32}$",
            "description": "The enrolled card handle from enrollment. Never a card number."
          },
          "domain": {
            "type": "string",
            "examples": ["example.com"]
          },
          "intent": {
            "type": "string",
            "const": "appraise"
          },
          "maxSpendUsd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Your hard ceiling for this charge. Below the price, the answer is ceiling_below_price and nothing is charged."
          }
        }
      },
      "CardAgentStatus": {
        "type": "object",
        "required": ["action", "version", "operationId"],
        "properties": {
          "action": {
            "const": "card_agent_status"
          },
          "version": {
            "const": "card-agent-1"
          },
          "operationId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          }
        }
      },
      "Resolve": {
        "type": "object",
        "required": ["domain", "intent"],
        "properties": {
          "domain": {
            "type": "string"
          },
          "intent": {
            "type": "string",
            "enum": ["screen", "appraise", "evidence", "acquire", "monitor"]
          },
          "maxSpendUsd": {
            "type": "number",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "AgentPurchase": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action",
          "version",
          "operationId",
          "grantId",
          "domain",
          "intent",
          "maxSpendUsd"
        ],
        "properties": {
          "action": {
            "const": "purchase"
          },
          "version": {
            "const": "purchase-1"
          },
          "operationId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{8,128}$",
            "description": "Persist before purchase. Reuse this identifier and the original request for every recovery attempt."
          },
          "grantId": {
            "type": "string",
            "format": "uuid",
            "description": "An existing operator-issued grant; this endpoint cannot create or widen it."
          },
          "domain": {
            "type": "string"
          },
          "intent": {
            "type": "string",
            "enum": ["screen", "appraise", "evidence", "acquire", "monitor"],
            "description": "Only products reporting live availability in GET terms can be delivered."
          },
          "maxSpendUsd": {
            "type": "number",
            "minimum": 0,
            "description": "Explicit USD-equivalent service-credit ceiling. A zero ceiling cannot buy a paid service."
          }
        }
      },
      "AgentPurchaseStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": ["action", "version", "operationId"],
        "properties": {
          "action": {
            "const": "purchase_status"
          },
          "version": {
            "const": "purchase-1"
          },
          "operationId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{8,128}$",
            "description": "Persist before purchase. Reuse this identifier and the original request for every recovery attempt."
          }
        }
      },
      "AgentStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": ["action", "version"],
        "properties": {
          "action": {
            "const": "agent_status"
          },
          "version": {
            "const": "agent-status-1"
          }
        },
        "description": "Read-only authenticated own-grant snapshot. Uses AgentBearer; identity comes exclusively from the verified token. No operation, funding, mutation, account initialization or engine call. Responses use private, no-store and Vary: Authorization."
      },
      "AgentGrantSnapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "agentId",
          "snapshotAt",
          "advisory",
          "grants",
          "truncated"
        ],
        "properties": {
          "version": {
            "const": "agent-status-1"
          },
          "agentId": {
            "type": "string",
            "format": "uuid"
          },
          "snapshotAt": {
            "type": "string",
            "format": "date-time"
          },
          "advisory": {
            "const": true
          },
          "truncated": {
            "type": "boolean",
            "description": "Grant count or the 128 KiB transport bound was exceeded; clients must refuse automatic selection from an incomplete snapshot."
          },
          "grants": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/AgentGrant"
            }
          },
          "cards": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/AgentEnrolledCard"
            },
            "description": "Optional for legacy snapshots. Existing enrolled-card summaries are advisory and confer no balance or card spending authority."
          },
          "recovery": {
            "$ref": "#/components/schemas/AgentRecoveryInbox",
            "description": "Optional for legacy snapshots. Read-only original-operation discovery, separate from grant selection and spending capacity."
          }
        }
      },
      "AgentEnrolledCard": {
        "type": "object",
        "additionalProperties": false,
        "required": ["cardRef", "brand", "last4", "status", "consent"],
        "properties": {
          "cardRef": {
            "type": "string",
            "minLength": 36,
            "maxLength": 36,
            "pattern": "^acr_[0-9a-f]{32}$"
          },
          "brand": {
            "type": "string"
          },
          "last4": {
            "type": "string",
            "minLength": 4,
            "maxLength": 4,
            "pattern": "^[0-9]{4}$"
          },
          "status": {
            "enum": ["active", "revoked", "needs_reenrollment"]
          },
          "consent": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "product",
              "perChargeCapCents",
              "dailyCapCents",
              "expiresAt"
            ],
            "properties": {
              "product": {
                "type": "string"
              },
              "perChargeCapCents": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "dailyCapCents": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991,
                "description": "Stored consent daily cap, at least the per-charge cap. Advisory; the purchase route rechecks consent."
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "AgentRecoveryInbox": {
        "type": "object",
        "additionalProperties": false,
        "required": ["version", "status", "entries", "truncated", "note"],
        "properties": {
          "version": {
            "const": "agent-recovery-1"
          },
          "status": {
            "enum": ["available", "unavailable"]
          },
          "entries": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AgentRecoveryEntry"
            },
            "description": "Up to 25 original operations per rail, 50 total, further bounded by 32 KiB encoded inbox size. Operation IDs are unique within each rail; the same ID can occur on both rails."
          },
          "truncated": {
            "type": "boolean"
          },
          "note": {
            "type": "string"
          }
        },
        "oneOf": [
          {
            "properties": {
              "status": {
                "const": "available"
              }
            }
          },
          {
            "properties": {
              "status": {
                "const": "unavailable"
              },
              "entries": {
                "maxItems": 0
              },
              "truncated": {
                "const": true
              }
            }
          }
        ],
        "description": "Advisory pointers only. Inspection starts no purchase, charge or delivery and grants no authority. Unavailable or truncated history is not empty-history or no-charge evidence. Hosted-card and wallet receipts require their original credentials and are not listed. Recorded states do not prove completed payment or outside revenue."
      },
      "AgentRecoveryOperationId": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]{8,128}$",
        "not": {
          "pattern": "\\s"
        }
      },
      "AgentRecoveryEntry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rail",
          "operationId",
          "domain",
          "recordedState",
          "createdAt",
          "readBack"
        ],
        "properties": {
          "rail": {
            "enum": ["balance", "card-agent"]
          },
          "operationId": {
            "$ref": "#/components/schemas/AgentRecoveryOperationId"
          },
          "domain": {
            "type": "string",
            "minLength": 3,
            "maxLength": 253,
            "pattern": "^[a-z0-9][a-z0-9.-]{1,251}[a-z0-9]$",
            "not": {
              "pattern": "\\s"
            }
          },
          "recordedState": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "readBack": {
            "type": "object",
            "additionalProperties": false,
            "required": ["tool", "arguments", "mayResumePaymentOrDelivery"],
            "properties": {
              "tool": {
                "enum": [
                  "appraisal_purchase_status",
                  "appraisal_card_order_status"
                ]
              },
              "arguments": {
                "type": "object",
                "additionalProperties": false,
                "required": ["operationId"],
                "properties": {
                  "operationId": {
                    "$ref": "#/components/schemas/AgentRecoveryOperationId"
                  }
                },
                "description": "Use the original operationId from this entry, authenticated as the same agent. Never create a replacement identifier to recover an uncertain purchase."
              },
              "mayResumePaymentOrDelivery": {
                "type": "boolean"
              }
            }
          }
        },
        "oneOf": [
          {
            "properties": {
              "rail": {
                "const": "balance"
              },
              "recordedState": {
                "enum": ["pending", "fulfilled", "refunded"]
              },
              "readBack": {
                "properties": {
                  "tool": {
                    "const": "appraisal_purchase_status"
                  },
                  "mayResumePaymentOrDelivery": {
                    "const": false
                  }
                }
              }
            }
          },
          {
            "properties": {
              "rail": {
                "const": "card-agent"
              },
              "recordedState": {
                "enum": [
                  "created",
                  "payment_submitted",
                  "paid",
                  "delivered",
                  "payment_failed",
                  "refunded"
                ]
              },
              "readBack": {
                "properties": {
                  "tool": {
                    "const": "appraisal_card_order_status"
                  },
                  "mayResumePaymentOrDelivery": {
                    "const": true
                  }
                }
              }
            }
          }
        ],
        "description": "Balance status reads are inert. Card-agent status can resume the original payment or delivery. Read-back does not grant permission for a new purchase."
      },
      "AgentGrant": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "products",
          "domains",
          "expiresAt",
          "revoked",
          "remainingMicrocredits",
          "perOperationMicrocredits",
          "remainingAttempts",
          "available"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "products": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Exact stored product scope; no wildcard semantics."
          },
          "domains": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "maxLength": 253
            },
            "description": "Exact stored domain scope; no implicit normalization or wildcard expansion."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "revoked": {
            "type": "boolean"
          },
          "remainingMicrocredits": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Minimum of grant budget minus spent and reserved credits, and associated account balance. Advisory, not a new reservation."
          },
          "perOperationMicrocredits": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "remainingAttempts": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "available": {
            "type": "boolean",
            "description": "Current nonsuspended, unrevoked, unexpired grant with positive capacity and attempts; exact scope and current price still require checking."
          }
        }
      }
    },
    "securitySchemes": {
      "AgentBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An existing operator-issued expiring ad_agent_ token. Required for purchase, purchase_status, card_agent_pay and card_agent_status; never place the token in JSON arguments."
      }
    }
  }
}
