{ "openapi": "3.1.0", "info": { "title": "Keelson API", "version": "0.0.0" }, "servers": [ { "url": "https://api.keelson.finance", "description": "Keelson's API, on the PayPal sandbox" } ], "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.1. An operator's agent uses client credentials; an app acting for a user uses the authorization code grant with PKCE (S256). Every token is requested for the resource `https://api.keelson.finance` (RFC 8707).", "flows": { "clientCredentials": { "tokenUrl": "https://api.keelson.finance/api/auth/oauth2/token", "scopes": { "countersign:write": "Countersign carts as the operator's own agent", "evidence:write": "Seal and store evidence", "evidence:disclose": "Disclose stored evidence items", "evidence:decrypt": "Decrypt sealed evidence originals", "alibis:read": "Read and verify Alibis", "disputes:read": "Read disputes and their attribution", "operators:write": "Link and manage operators", "merchants:write": "Manage a merchant's settings", "mandates:request": "Ask the user for a mandate or a change of one", "purchases:write": "Check and countersign carts for the user", "offline_access": "Stay connected with a refresh token" } }, "authorizationCode": { "authorizationUrl": "https://api.keelson.finance/api/auth/oauth2/authorize", "tokenUrl": "https://api.keelson.finance/api/auth/oauth2/token", "refreshUrl": "https://api.keelson.finance/api/auth/oauth2/token", "scopes": { "countersign:write": "Countersign carts as the operator's own agent", "evidence:write": "Seal and store evidence", "evidence:disclose": "Disclose stored evidence items", "evidence:decrypt": "Decrypt sealed evidence originals", "alibis:read": "Read and verify Alibis", "disputes:read": "Read disputes and their attribution", "operators:write": "Link and manage operators", "merchants:write": "Manage a merchant's settings", "mandates:request": "Ask the user for a mandate or a change of one", "purchases:write": "Check and countersign carts for the user", "offline_access": "Stay connected with a refresh token" } } } }, "session": { "type": "apiKey", "in": "cookie", "name": "__Secure-better-auth.session_token", "description": "The session of a user signed in to the Keelson app." } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": {} }, "CreatedMandate": { "type": "object", "properties": { "id": { "type": "string" }, "mandateHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "state": { "type": "string", "enum": [ "SIGNED", "ACTIVE" ], "description": "`ACTIVE` at once when the mandate allows several merchants: each cart is then held on its own." }, "openMandate": { "type": [ "string", "null" ], "description": "The open mandate (L2) the TEE issued; the agent closes it per purchase." } }, "required": [ "id", "mandateHash", "state", "openMandate" ] }, "CreateMandate": { "type": "object", "properties": { "payloadSd": { "type": "object", "additionalProperties": {}, "description": "The SD-JWT payload with its `_sd` digests, as signed." }, "disclosures": { "type": "array", "items": { "type": "string" }, "maxItems": 1024, "description": "Every disclosure of the payload; each digest must resolve." }, "commitment": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "`C_m`; must equal the payload's `zk.commitment`." }, "salt": { "type": "string", "pattern": "^0x[0-9a-f]{32}$", "description": "The salt that opens `C_m`; the TEE needs it to issue the mandate." }, "assertion": { "$ref": "#/components/schemas/PasskeyAssertion" }, "connection": { "type": "object", "properties": { "code": { "type": "string", "minLength": 8, "maxLength": 16 }, "askAboveMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "code" ], "description": "The agent's request this mandate approves, by its user code. The mandate must name the asking agent's operator and grant no more than it asked; `askAboveMinor` may only be lower too." } }, "required": [ "payloadSd", "disclosures", "commitment", "assertion" ] }, "PasskeyAssertion": { "type": "object", "properties": { "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" }, "credentialId": { "type": "string" }, "userHandle": { "type": "string" } }, "required": [ "authenticatorData", "clientDataJSON", "signature", "credentialId" ], "description": "A WebAuthn or Secure Payment Confirmation assertion, base64url fields." }, "Mandates": { "type": "object", "properties": { "mandates": { "type": "array", "items": { "$ref": "#/components/schemas/MandateSummary" } } }, "required": [ "mandates" ] }, "MandateSummary": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "DRAFT", "COMPILED", "SIGNED", "HOLD_PENDING", "ACTIVE", "EXHAUSTED", "EXPIRED", "REVOKED" ] }, "budget": { "$ref": "#/components/schemas/MandateBudget" }, "merchantIds": { "type": "array", "items": { "type": "string" } }, "holdMode": { "type": "string", "enum": [ "mandate", "per_purchase" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "state", "budget", "merchantIds", "holdMode", "expiresAt", "createdAt" ] }, "MandateBudget": { "type": "object", "properties": { "currency": { "type": "string" }, "maxMinor": { "type": "string", "pattern": "^\\d+$" }, "remainingMinor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "currency", "maxMinor", "remainingMinor" ], "description": "The mandate's budget and what is left of it, in minor units." }, "Mandate": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "DRAFT", "COMPILED", "SIGNED", "HOLD_PENDING", "ACTIVE", "EXHAUSTED", "EXPIRED", "REVOKED" ] }, "rail": { "type": "string", "enum": [ "paypal", "card" ], "description": "`card` when each purchase is paid with its own single-use card." }, "mandateHash": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$" }, "budget": { "$ref": "#/components/schemas/MandateBudget" }, "expiresAt": { "type": "string", "format": "date-time" }, "hold": { "anyOf": [ { "$ref": "#/components/schemas/MandateHold" }, { "type": "null" } ], "description": "The PayPal hold of the mandate's budget, once its order exists." }, "card": { "anyOf": [ { "$ref": "#/components/schemas/MandateCard" }, { "type": "null" } ], "description": "The card rendered from the stored payload, before any checkout evidence." }, "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/MandatePurchase" }, "description": "The mandate's latest 100 purchases, newest first." }, "pendingHolds": { "type": "array", "items": { "$ref": "#/components/schemas/PendingPurchaseHold" }, "description": "Purchase holds of a several-store mandate still waiting for the buyer's PayPal approval, oldest first. Later changes arrive as `mandate.purchase_hold` events." } }, "required": [ "id", "state", "rail", "mandateHash", "budget", "expiresAt", "hold", "card", "purchases", "pendingHolds" ] }, "MandateHold": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mandate", "per_purchase" ] }, "orderId": { "type": "string" }, "authorizationId": { "type": [ "string", "null" ], "description": "The authorization captures use: the original, or its reauthorization." }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reauthorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "remainingMinor": { "type": "string", "pattern": "^\\d+$" }, "state": { "type": "string", "enum": [ "PENDING", "AUTHORIZED", "RELEASED" ], "description": "`PENDING` until authorized; `RELEASED` once the mandate ended and the hold was voided or captured." } }, "required": [ "mode", "orderId", "authorizationId", "authorizedAt", "reauthorizedAt", "remainingMinor", "state" ] }, "MandateCard": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "color": { "type": "string", "enum": [ "green", "amber", "gray" ] }, "answers": { "type": "string", "enum": [ "Keelson", "Agent operator", "You" ] } }, "required": [ "field", "label", "values", "color", "answers" ] } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "rows", "warnings" ] }, "MandatePurchase": { "type": "object", "properties": { "id": { "type": "string", "description": "The purchase's ULID, which is also its Alibi id." }, "merchantId": { "type": "string" }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" }, "breakdown": { "$ref": "#/components/schemas/CheckoutBreakdown" } }, "required": [ "currency", "minor" ] }, "createdAt": { "type": "string", "format": "date-time" }, "state": { "type": "string" }, "logIndex": { "type": "string", "description": "The leaf's index in the Alibi log." }, "coverage": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": [ "string", "null" ] } }, "required": [ "chainId", "txHash" ], "description": "The `lockCoverage` transaction of the operator's bond." }, "capture": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "invoiceId", "status" ], "description": "The PayPal capture of the countersigned amount." }, "failure": { "type": "object", "properties": { "step": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "step", "reason" ], "description": "The step that failed and why; nothing was captured." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "For a `DENIED` cart, the mandate fields whose check failed." }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] } }, "required": [ "field", "mandate", "cart" ] }, "description": "For a `DENIED` cart, each failed field with what the mandate allowed and what the cart had, as text." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] }, "pass": { "type": "boolean" } }, "required": [ "field", "mandate", "cart", "pass" ] }, "description": "For a purchase the engine checked, each mandate field with what the mandate allowed, what the cart had and whether it held." }, "card": { "type": "object", "properties": { "issuer": { "type": "string" }, "lastFour": { "type": "string" }, "state": { "type": "string" }, "expiresAt": { "type": "string" }, "controls": { "type": "object", "additionalProperties": {} }, "settledMinor": { "type": [ "string", "null" ] }, "chargebacks": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Chargebacks filed through the card issuer over this purchase." }, "bondClaimMinor": { "type": "string", "description": "The most a bond claim over this purchase may pay: the settled amount less what chargebacks returned; 0 while one is open." }, "authorizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amountMinor": { "type": "string" }, "currency": { "type": "string" }, "mcc": { "type": "string" }, "merchantName": { "type": "string" }, "merchantCountry": { "type": "string" }, "approved": { "type": "boolean" }, "failedMask": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "legs": { "type": "object", "properties": { "tdx": { "type": "boolean" }, "nitro": { "type": "boolean" } }, "required": [ "tdx", "nitro" ] }, "latencyMs": { "type": "integer" }, "at": { "type": "string" } }, "required": [ "id", "amountMinor", "currency", "mcc", "merchantName", "merchantCountry", "approved", "failedMask", "reason", "legs", "latencyMs", "at" ] } } }, "required": [ "issuer", "lastFour", "state", "expiresAt", "controls", "settledMinor", "chargebacks", "bondClaimMinor", "authorizations" ], "description": "A card purchase: its single-use card (never its number) and every authorization the card network sent it, with both legs' decision. `CAPTURED` once the merchant's capture settles." }, "live": { "type": "object", "properties": { "store": { "type": "string" }, "transactionId": { "type": [ "string", "null" ] } }, "required": [ "store", "transactionId" ], "description": "A purchase the buyer pays at the store's own checkout: the store's origin and the PayPal transaction id once the agent recorded it. Never covered nor captured." }, "disputes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ATTRIBUTED", "RESOLVED" ] } }, "required": [ "id", "state" ] }, "description": "PayPal disputes over the purchase; `GET /v1/disputes/{id}` has each." } }, "required": [ "id", "merchantId", "amount", "createdAt", "state", "disputes" ] }, "CheckoutBreakdown": { "type": "object", "properties": { "items": { "type": "string" }, "tax": { "type": "string" }, "shipping": { "type": "string" }, "discount": { "type": "string" } }, "required": [ "items", "tax", "shipping", "discount" ], "description": "What the countersigned total is made of, in minor units: the items, plus tax and shipping, less discounts. Absent for purchases countersigned without it." }, "PendingPurchaseHold": { "type": "object", "properties": { "requestId": { "type": "string" }, "orderId": { "type": "string", "description": "The PayPal order the buyer approves." }, "merchant": { "type": "string" }, "amountMinor": { "type": "string" } }, "required": [ "requestId", "orderId", "merchant", "amountMinor" ] }, "PayPalClient": { "type": "object", "properties": { "clientId": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "clientId", "environment" ] }, "HoldOrder": { "type": "object", "properties": { "orderId": { "type": "string" }, "state": { "type": "string", "enum": [ "HOLD_PENDING" ] }, "approved": { "type": "boolean", "description": "The user's saved PayPal paid the order, so PayPal shows the buyer nothing: authorize it next." } }, "required": [ "orderId", "state", "approved" ] }, "AuthorizedHold": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "ACTIVE" ] }, "authorizationId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When PayPal expires the authorization, 29 days after it was created." } }, "required": [ "state", "authorizationId", "expiresAt" ] }, "PendingHold": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "HOLD_PENDING" ] }, "authorizationId": { "type": "string" } }, "required": [ "state", "authorizationId" ], "description": "PayPal holds the authorization for review; Keelson activates it once created." }, "AuthorizeHold": { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "orderId" ], "description": "The order the buyer approved." }, "PayPalSetupToken": { "type": "object", "properties": { "setupToken": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9A-Za-z_-]+$" } }, "required": [ "setupToken" ] }, "PayPalWallet": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "description": "The PayPal account, as PayPal names it." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "email", "createdAt" ], "description": "The PayPal the user saved for holds under the mandates they sign." }, "PurchaseHoldOrder": { "type": "object", "properties": { "requestId": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "requestId", "orderId" ] }, "CreatePurchaseHold": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "The request id the purchase is countersigned under." }, "merchant": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "amountMinor": { "type": "string", "pattern": "^[1-9]\\d{0,17}$", "description": "The checkout total the purchase is countersigned for, tax and shipping included, in minor units." }, "cartHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "closedMandate": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The mandate's open mandate closed by the agent key over `requestId` and `cartHash`; it proves the caller is the mandate's agent." } }, "required": [ "requestId", "merchant", "currency", "amountMinor", "cartHash", "closedMandate" ] }, "AuthorizedPurchaseHold": { "type": "object", "properties": { "requestId": { "type": "string" }, "state": { "type": "string", "enum": [ "AUTHORIZED", "PENDING" ] }, "authorizationId": { "type": "string" } }, "required": [ "requestId", "state", "authorizationId" ], "description": "`PENDING` while PayPal reviews the authorization; asking again once it is created authorizes the hold." }, "AuthorizePurchaseHold": { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "orderId" ], "description": "The order the buyer approved." }, "RevokedMandate": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "REVOKED" ] } }, "required": [ "state" ] }, "RevokingMandate": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "REVOKING" ] } }, "required": [ "state" ], "description": "Purchases already countersigned may still be captured; the hold is voided after them." }, "DeviceAuthorization": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" }, "request_id": { "type": "string", "description": "The request's id: `GET /v1/connections/requests/{id}` reads its state without spending the device code." }, "match_number": { "type": "integer", "minimum": 10, "maximum": 99, "description": "Show it beside the link: the user picks it out of three before the request opens, so a link relayed by someone else does not." } }, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval", "request_id" ], "description": "RFC 8628 §3.2. Show `user_code` and `verification_uri` to the user, then poll `POST /v1/connections/token` every `interval` seconds." }, "ConnectionRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "example": "Claude Code" }, "reason": { "type": "string", "minLength": 100, "maxLength": 1000, "description": "Why the agent asks, in its own words; the user reads it before approving." }, "limits": { "$ref": "#/components/schemas/ConnectionLimits" } }, "required": [ "name", "reason", "limits" ] }, "ConnectionLimits": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ], "default": "USD" }, "perPurchaseMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Most one purchase may cost, minor units." }, "totalMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Most all purchases may cost together." }, "merchants": { "type": "array", "items": { "type": "string", "enum": [ "mrc_runfast" ] }, "minItems": 1, "maxItems": 1, "default": [ "mrc_runfast" ], "description": "Onboarded merchant ids; every one when left out." }, "until": { "type": "string", "format": "date-time", "description": "When the mandate ends." }, "askAboveMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Above this a purchase waits for the user's one-time approval, although the limits allow it." } }, "required": [ "perPurchaseMinor", "totalMinor", "until" ] }, "ConnectionApproved": { "type": "object", "properties": { "mandate_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "connect", "once" ] } }, "required": [ "mandate_id", "kind" ] }, "ConnectionTokenError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "authorization_pending", "slow_down", "access_denied", "expired_token", "invalid_grant", "unsupported_grant_type" ] }, "error_description": { "type": "string" }, "interval": { "type": "integer" } }, "required": [ "error", "error_description" ] }, "Connection": { "type": "object", "properties": { "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "connect", "once", "change" ], "description": "`connect`: standing limits. `once`: one cart its mandate does not allow. `change`: new limits that replace `parent`, whose hold is released." }, "state": { "type": "string", "enum": [ "PENDING", "APPROVED", "DENIED", "EXPIRED" ] }, "name": { "type": "string" }, "reason": { "type": "string" }, "agent": { "type": "object", "properties": { "agentId": { "type": "string" }, "operator": { "type": "string" }, "bond": { "type": [ "object", "null" ], "properties": { "asset": { "type": "string" }, "min": { "type": "number" }, "vault": { "type": "string" } }, "required": [ "asset", "min", "vault" ] } }, "required": [ "agentId", "operator", "bond" ] }, "limits": { "type": "object", "properties": { "currency": { "type": "string" }, "perPurchaseMinor": { "type": "string" }, "totalMinor": { "type": "string" }, "askAboveMinor": { "type": [ "string", "null" ] }, "merchants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "until": { "type": "string" } }, "required": [ "currency", "perPurchaseMinor", "totalMinor", "askAboveMinor", "merchants", "until" ] }, "parent": { "type": [ "object", "null" ], "properties": { "mandateId": { "type": "string" }, "perPurchaseMinor": { "type": "string" }, "totalMinor": { "type": "string" }, "remainingMinor": { "type": "string" }, "until": { "type": "string" } }, "required": [ "mandateId", "perPurchaseMinor", "totalMinor", "remainingMinor", "until" ] }, "mandateId": { "type": [ "string", "null" ] }, "cart": { "type": [ "object", "null" ], "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "currency": { "type": "string" }, "totalMinor": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "size": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "qty": { "type": "integer" }, "unitMinor": { "type": "string" } }, "required": [ "sku", "size", "color", "category", "qty", "unitMinor" ] } } }, "required": [ "merchant", "currency", "totalMinor", "lines" ], "description": "For `once`: the cart the agent tried, as it saw it." }, "checks": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] }, "pass": { "type": "boolean" } }, "required": [ "field", "mandate", "cart", "pass" ] }, "description": "For `once`: each mandate field against the cart; the failing ones are why it is paused. `askAbove` fails when the cart is above the user's ask-me amount." }, "match": { "type": [ "object", "null" ], "properties": { "options": { "type": "array", "items": { "type": "integer" } }, "matched": { "type": "boolean" } }, "required": [ "options", "matched" ], "description": "When the user must pick the agent's number before approving: three numbers, one the agent shows. Null when the request needs no match." }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "code", "kind", "state", "name", "reason", "agent", "limits", "parent", "mandateId", "cart", "checks", "match", "expiresAt", "createdAt" ] }, "ConnectionRequestState": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "connect", "once", "change" ] }, "state": { "type": "string", "enum": [ "PENDING", "APPROVED", "DENIED", "EXPIRED" ] }, "mandateId": { "type": [ "string", "null" ], "description": "The mandate the user signed." }, "parentMandateId": { "type": [ "string", "null" ] }, "userCode": { "type": "string" }, "approvalUrl": { "type": "string" }, "matchNumber": { "type": [ "integer", "null" ] }, "expiresAt": { "type": "string" }, "interval": { "type": "integer" }, "operatorAgentId": { "type": "string", "description": "The ERC-8004 agent id of the operator the mandate names, in decimal." } }, "required": [ "id", "kind", "state", "mandateId", "parentMandateId", "userCode", "approvalUrl", "matchNumber", "expiresAt", "interval", "operatorAgentId" ] }, "ConnectionDraft": { "type": "object", "properties": { "limits": { "type": "object", "properties": { "perPurchaseMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "totalMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "merchants": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "until": { "type": "string", "format": "date-time" }, "askAboveMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "perPurchaseMinor", "totalMinor", "merchants", "until" ] }, "credentialId": { "type": "string", "minLength": 1 } }, "required": [ "limits" ] }, "MandateChangeRequest": { "type": "object", "properties": { "note": { "type": "string", "minLength": 10, "maxLength": 280, "description": "Why the agent needs more room, in one line the user reads verbatim, e.g. 'Needs $40 more for shipping'." }, "limits": { "type": "object", "properties": { "perPurchaseMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "totalMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "until": { "type": "string", "format": "date-time" }, "askAboveMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "description": "The limits asked for; the mandate's own where left out." } }, "required": [ "note" ] }, "CartCheck": { "type": "object", "properties": { "canAttempt": { "type": "boolean", "description": "Whether a countersign of this cart would pass the mandate as it stands now." }, "needsApproval": { "type": "boolean", "description": "The cart passes, and is above the user's ask-me amount: the countersign pauses it for their one-time approval." }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "field:total" }, "field": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "next": { "type": "string", "description": "What the agent does about it." } }, "required": [ "code", "field", "message", "next" ] } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] }, "pass": { "type": "boolean" } }, "required": [ "field", "mandate", "cart", "pass" ] } } }, "required": [ "canAttempt", "needsApproval", "blockers", "checks" ] }, "Cart": { "type": "object", "properties": { "merchant": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 256 }, "size": { "type": [ "string", "null" ], "maxLength": 256 }, "color": { "type": [ "string", "null" ], "maxLength": 256 }, "category": { "type": "string", "maxLength": 256 }, "qty": { "type": "integer", "exclusiveMinimum": 0 }, "unit_minor": { "type": "integer", "minimum": 0 } }, "required": [ "sku", "category", "qty", "unit_minor" ] }, "minItems": 1, "maxItems": 32 }, "return_days": { "type": "integer", "minimum": 0 }, "returns_free": { "type": "boolean" } }, "required": [ "merchant", "currency", "lines", "return_days", "returns_free" ] }, "EmbedOrigins": { "type": "object", "properties": { "origins": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "minItems": 1, "maxItems": 5, "example": [ "https://agents.example.com" ] } }, "required": [ "origins" ] }, "EmbedUrl": { "type": "object", "properties": { "url": { "type": "string" }, "ref": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "url", "ref", "expires_in" ] }, "EmbedSession": { "type": "object", "properties": { "session": { "type": "string" }, "embed": { "$ref": "#/components/schemas/EmbedRequest" } }, "required": [ "session", "embed" ] }, "EmbedRequest": { "type": "object", "properties": { "ref": { "type": "string" }, "origin": { "type": "string" }, "request": { "$ref": "#/components/schemas/Connection" }, "signer": { "$ref": "#/components/schemas/EmbedSigner" }, "matchNumber": { "type": [ "integer", "null" ] } }, "required": [ "ref", "origin", "request", "signer", "matchNumber" ] }, "EmbedSigner": { "type": [ "object", "null" ], "properties": { "passkeys": { "type": "array", "items": { "type": "object", "properties": { "credentialId": { "type": "string" }, "payment": { "type": "boolean" } }, "required": [ "credentialId", "payment" ] } }, "credentialId": { "type": [ "string", "null" ] } }, "required": [ "passkeys", "credentialId" ] }, "WebAuthnResponse": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 1024 }, "rawId": { "type": "string", "maxLength": 1024 }, "type": { "type": "string", "enum": [ "public-key" ] }, "response": { "type": "object", "additionalProperties": {} }, "authenticatorAttachment": { "type": "string", "maxLength": 32 }, "clientExtensionResults": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "rawId", "type", "response" ], "description": "`PublicKeyCredential.toJSON()` of the ceremony the frame started." }, "EmbedLink": { "type": "object", "properties": { "nonce": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "nonce", "expires_in" ] }, "EmbedLinked": { "type": "object", "properties": { "origin": { "type": "string" }, "grant": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "origin", "grant", "expires_in" ] }, "Agent": { "type": "object", "properties": { "agentId": { "type": "string" }, "clientId": { "type": [ "string", "null" ], "description": "The app acting through Keelson's hosted operator, which many apps share: disconnect it alone with `?client=`. Null for an agent's own operator, and for the hosted operator's mandates no app holds (`Unknown app`)." }, "name": { "type": "string" }, "operator": { "type": "string" }, "connected": { "type": "boolean" }, "mandate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "currency": { "type": "string" }, "maxMinor": { "type": "string" }, "remainingMinor": { "type": "string" }, "expiresAt": { "type": "string" }, "merchants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "state", "currency", "maxMinor", "remainingMinor", "expiresAt", "merchants" ], "description": "The live mandate the agent buys under, if any." }, "lastActivityAt": { "type": "string" } }, "required": [ "agentId", "clientId", "name", "operator", "connected", "mandate", "lastActivityAt" ] }, "PendingApproval": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "amountMinor": { "type": "string" }, "overMinor": { "type": [ "string", "null" ], "description": "How far above the mandate the cart is; null when it is the store." }, "merchant": { "type": "string" }, "mandateId": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "code", "name", "currency", "amountMinor", "overMinor", "merchant", "mandateId", "expiresAt" ] }, "AgentStop": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "integer", "description": "Mandates ended." }, "released": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] }, "description": "What PayPal held for them, per currency, now released." }, "mandateHashes": { "type": "array", "items": { "type": "string" }, "description": "Hex of the stopped mandates' hashes. The stop leaf commits to their digest: no Alibi leaf after it may carry one." }, "releasing": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] }, "description": "Holds backing purchases already countersigned: released once those are captured." }, "logIndexes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The stop leaf's index in each Alibi log origin. It is appended once no purchase of the stopped mandates can still be logged, so no Alibi leaf after it carries one of their hashes." }, "logged": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "revoked", "released", "mandateHashes", "releasing", "logIndexes", "logged", "createdAt" ] }, "AgentsRevoked": { "type": "object", "properties": { "revoked": { "type": "integer", "description": "Mandates stopped." } }, "required": [ "revoked" ] }, "ActivityRow": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string" }, "tone": { "type": "string", "enum": [ "good", "warn", "bad" ] }, "line": { "type": "string", "example": "Claude Code bought $94.00 at RunFast." }, "agentId": { "type": [ "string", "null" ] }, "purchaseId": { "type": [ "string", "null" ] }, "mandateId": { "type": [ "string", "null" ] }, "href": { "type": [ "string", "null" ] }, "alibiUrl": { "type": [ "string", "null" ] }, "logIndex": { "type": [ "string", "null" ] } }, "required": [ "id", "at", "tone", "line", "agentId", "purchaseId", "mandateId", "href", "alibiUrl", "logIndex" ] }, "PushSubscription": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 2048, "format": "uri" }, "expirationTime": { "type": [ "number", "null" ] }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "pattern": "^[A-Za-z0-9_-]{80,100}$" }, "auth": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,32}$" } }, "required": [ "p256dh", "auth" ] } }, "required": [ "endpoint", "keys" ] }, "AlertEmail": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "confirmed": { "type": "boolean" } }, "required": [ "address", "confirmed" ] }, "SentEmail": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "event": { "type": "string" }, "subject": { "type": "string" }, "subjectId": { "type": [ "string", "null" ] }, "logIndex": { "type": [ "string", "null" ] }, "alibiUrl": { "type": [ "string", "null" ] }, "sentAt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "address", "event", "subject", "subjectId", "logIndex", "alibiUrl", "sentAt", "error", "createdAt" ] }, "CompiledMandate": { "type": "object", "properties": { "mandateDraft": { "$ref": "#/components/schemas/MandateDraft" }, "card": { "$ref": "#/components/schemas/MandateCard" }, "ambiguous": { "type": "array", "items": { "type": "string", "enum": [ "mode", "recurrence", "total", "currency", "budget", "merchant", "card", "deadline", "quantity", "items", "category", "variant", "return_policy", "agent", "bond", "subjective", "summary" ] }, "description": "Card fields the compilations disagreed on or the request left unstated, shown gray for the user to settle. Pass them to `prepareSigning` so the card the user signs shows them gray too." }, "check": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "refused", "failed", "aborted", "skipped" ] }, "discrepancies": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "field": { "type": "string" }, "issue": { "type": "string" } }, "required": [ "field", "issue" ] } } }, "required": [ "status", "discrepancies" ], "description": "The round trip of the card against the request. Only `ok` means it was checked." } }, "required": [ "mandateDraft", "card", "ambiguous", "check" ] }, "MandateDraft": { "type": "object", "properties": { "v": { "type": "string", "enum": [ "keelson.mandate.1" ] }, "mid": { "type": "string" }, "iat": { "type": "integer", "minimum": 0 }, "nbf": { "type": "integer", "minimum": 0 }, "exp": { "type": "integer", "minimum": 0 }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "mode": { "type": "string", "enum": [ "immediate", "autonomous" ] }, "user": { "type": "object", "properties": { "sub": { "type": "string" }, "cred": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "rp_id": { "type": "string" }, "jwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "EC" ] }, "crv": { "type": "string", "enum": [ "P-256" ] }, "x": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "y": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } }, "required": [ "kty", "crv", "x", "y" ], "additionalProperties": false } }, "required": [ "id", "rp_id", "jwk" ], "additionalProperties": false }, "app_login_id": { "type": "string" } }, "required": [ "sub", "cred", "app_login_id" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "operator": { "type": "object", "properties": { "agent_registry": { "type": "string" }, "agent_id": { "type": "string" } }, "required": [ "agent_registry", "agent_id" ], "additionalProperties": false }, "cnf": { "type": "object", "properties": { "jwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "EC" ] }, "crv": { "type": "string", "enum": [ "P-256" ] }, "x": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "y": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "kid": { "type": "string" } }, "required": [ "kty", "crv", "x", "y", "kid" ], "additionalProperties": false } }, "required": [ "jwk" ], "additionalProperties": false }, "bond": { "type": "object", "properties": { "vault": { "type": "string" }, "asset": { "type": "string" }, "min": { "type": "integer", "minimum": 0 } }, "required": [ "vault", "asset", "min" ], "additionalProperties": false } }, "required": [ "operator", "cnf", "bond" ], "additionalProperties": false }, "payment": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "paypal", "card" ] }, "currency": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ] }, "constraints": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.amount_range" ] }, "max": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ] } }, "required": [ "type", "max", "currency" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.budget" ] }, "max": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ] } }, "required": [ "type", "max", "currency" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.allowed_payees" ] }, "allowed": { "type": "array", "items": { "type": "object", "properties": { "paypal_merchant_id": { "type": "string" } }, "required": [ "paypal_merchant_id" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "type", "allowed" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.execution_date" ] }, "not_after": { "type": "string", "format": "date-time" } }, "required": [ "type", "not_after" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.card_controls" ] }, "single_use": { "type": "boolean", "enum": [ true ] }, "mcc_table": { "type": "string", "enum": [ "v1" ] } }, "required": [ "type", "single_use", "mcc_table" ], "additionalProperties": false } ] } } }, "required": [ "rail", "currency", "constraints" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "constraints": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "checkout.allowed_merchants" ] }, "allowed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string" }, "paypal_merchant_id": { "type": "string" }, "mcc": { "type": "array", "items": { "type": "string", "enum": [ "4111", "4121", "5300", "5310", "5311", "5411", "5441", "5462", "5499", "5651", "5661", "5691", "5732", "5734", "5812", "5814", "5912", "5941", "5942", "5945", "5977", "5992", "5995", "5999", "7832" ] }, "minItems": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "id", "name" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "type", "allowed" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "checkout.line_items" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "acceptable_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1 }, "quantity": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "acceptable_items", "quantity" ], "additionalProperties": false } } }, "required": [ "type", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "keelson.category" ] }, "allow": { "type": "array", "items": { "type": "string", "enum": [ "gpt:1", "gpt:166", "gpt:8", "gpt:537", "gpt:111", "gpt:141", "gpt:222", "gpt:412", "gpt:436", "gpt:632", "gpt:469", "gpt:536", "gpt:5181", "gpt:772", "gpt:783", "gpt:922", "gpt:5605", "gpt:2092", "gpt:988", "gpt:1239", "gpt:888", "gpt:187" ] }, "minItems": 1 }, "deny": { "type": "array", "items": { "type": "string", "enum": [ "gpt:1", "gpt:166", "gpt:8", "gpt:537", "gpt:111", "gpt:141", "gpt:222", "gpt:412", "gpt:436", "gpt:632", "gpt:469", "gpt:536", "gpt:5181", "gpt:772", "gpt:783", "gpt:922", "gpt:5605", "gpt:2092", "gpt:988", "gpt:1239", "gpt:888", "gpt:187" ] } } }, "required": [ "type", "allow", "deny" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "keelson.attributes" ] }, "must": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "type", "must" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "keelson.returns" ] }, "min_days": { "type": "integer", "minimum": 0 }, "free": { "type": "boolean" } }, "required": [ "type", "min_days", "free" ], "additionalProperties": false } ] } } }, "required": [ "constraints" ], "additionalProperties": false }, "intent": { "type": "object", "properties": { "prompt_summary": { "type": "string" }, "prompt_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "subjective": { "type": "array", "items": { "type": "string" } } }, "required": [ "prompt_summary", "prompt_hash", "subjective" ], "additionalProperties": false }, "policy": { "type": "object", "properties": { "engine": { "type": "string" }, "version": { "type": "string" }, "policy_set_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "measurements": { "type": "array", "items": { "type": "string" } } }, "required": [ "engine", "version", "policy_set_hash", "measurements" ], "additionalProperties": false }, "consent": { "type": "object", "properties": { "terms_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "instruction_use": { "type": "boolean" }, "responsibility_ack": { "type": "boolean" }, "merchant_policy_ack": { "type": "string" }, "recurrence_ack": { "type": "boolean" } }, "required": [ "terms_hash", "instruction_use", "responsibility_ack", "merchant_policy_ack", "recurrence_ack" ], "additionalProperties": false }, "zk": { "type": "object", "properties": { "commitment": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "commitment" ], "additionalProperties": false }, "risk_data": { "type": "object", "properties": { "device_fp": { "type": "string" }, "ip": { "type": "string" } }, "required": [ "device_fp", "ip" ], "additionalProperties": false }, "embed": { "type": "object", "properties": { "top_origin": { "type": "string" } }, "required": [ "top_origin" ], "additionalProperties": false }, "fx": { "type": "object", "properties": { "max_spread_bps": { "type": "integer", "minimum": 0, "maximum": 3000 } }, "required": [ "max_spread_bps" ], "additionalProperties": false } }, "required": [ "v", "mid", "iat", "nbf", "exp", "nonce", "mode", "user", "agent", "payment", "checkout", "intent", "policy", "consent", "zk", "risk_data" ], "additionalProperties": false, "description": "The compiled `keelson.mandate.1` payload, unsigned; its commitment is zero." }, "CompileMandate": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The shopping request in natural language, at most 2000 UTF-16 code units.", "example": "Running shoes, size 10, under $100, free returns, by Friday" }, "credentialId": { "type": "string", "minLength": 1, "description": "The passkey that will sign the mandate; defaults to the most recent one." }, "mode": { "type": "string", "enum": [ "immediate", "autonomous" ], "default": "autonomous", "description": "Whether the user is present at checkout (`immediate`) or not (`autonomous`)." } }, "required": [ "prompt" ] }, "Countersigned": { "type": "object", "properties": { "purchaseId": { "type": "string" }, "mode": { "type": "string", "enum": [ "2of2", "degraded" ], "description": "`degraded` when leg B was unreachable and only leg A signed." }, "decision": { "type": "string", "enum": [ "allow", "deny" ] }, "countersign": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The EIP-712 `Countersign` message, as decimal strings." }, "digest": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "signatures": { "type": "object", "properties": { "tdx": { "type": "string", "pattern": "^0x[0-9a-f]{130}$" }, "nitro": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{130}$" } }, "required": [ "tdx", "nitro" ] }, "signers": { "type": "object", "properties": { "tdx": { "type": "string" }, "nitro": { "type": [ "string", "null" ] } }, "required": [ "tdx", "nitro" ] }, "trace": { "description": "The `keelson.eval/1` trace both legs signed over." }, "approval": { "$ref": "#/components/schemas/OnceApproval" }, "state": { "type": "string", "description": "`CAPTURED` once logged, covered and captured; `FAILED` with `failure` when a step refused; `COUNTERSIGNED`, `LOGGED` or `COVERED` while a step is pending; `DENIED` for a DENY." }, "logIndex": { "type": "string", "description": "The leaf's index in the Alibi log." }, "coverage": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": [ "string", "null" ] } }, "required": [ "chainId", "txHash" ], "description": "The `lockCoverage` transaction of the operator's bond." }, "capture": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "invoiceId", "status" ], "description": "The PayPal capture of the countersigned amount." }, "failure": { "type": "object", "properties": { "step": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "step", "reason" ], "description": "The step that failed and why; nothing was captured." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "For a `DENIED` cart, the mandate fields whose check failed." }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] } }, "required": [ "field", "mandate", "cart" ] }, "description": "For a `DENIED` cart, each failed field with what the mandate allowed and what the cart had, as text." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] }, "pass": { "type": "boolean" } }, "required": [ "field", "mandate", "cart", "pass" ] }, "description": "For a purchase the engine checked, each mandate field with what the mandate allowed, what the cart had and whether it held." }, "card": { "type": "object", "properties": { "issuer": { "type": "string" }, "lastFour": { "type": "string" }, "state": { "type": "string" }, "expiresAt": { "type": "string" }, "controls": { "type": "object", "additionalProperties": {} }, "settledMinor": { "type": [ "string", "null" ] }, "chargebacks": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Chargebacks filed through the card issuer over this purchase." }, "bondClaimMinor": { "type": "string", "description": "The most a bond claim over this purchase may pay: the settled amount less what chargebacks returned; 0 while one is open." }, "authorizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amountMinor": { "type": "string" }, "currency": { "type": "string" }, "mcc": { "type": "string" }, "merchantName": { "type": "string" }, "merchantCountry": { "type": "string" }, "approved": { "type": "boolean" }, "failedMask": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "legs": { "type": "object", "properties": { "tdx": { "type": "boolean" }, "nitro": { "type": "boolean" } }, "required": [ "tdx", "nitro" ] }, "latencyMs": { "type": "integer" }, "at": { "type": "string" } }, "required": [ "id", "amountMinor", "currency", "mcc", "merchantName", "merchantCountry", "approved", "failedMask", "reason", "legs", "latencyMs", "at" ] } } }, "required": [ "issuer", "lastFour", "state", "expiresAt", "controls", "settledMinor", "chargebacks", "bondClaimMinor", "authorizations" ], "description": "A card purchase: its single-use card (never its number) and every authorization the card network sent it, with both legs' decision. `CAPTURED` once the merchant's capture settles." }, "live": { "type": "object", "properties": { "store": { "type": "string" }, "transactionId": { "type": [ "string", "null" ] } }, "required": [ "store", "transactionId" ], "description": "A purchase the buyer pays at the store's own checkout: the store's origin and the PayPal transaction id once the agent recorded it. Never covered nor captured." } }, "required": [ "purchaseId", "mode", "decision", "countersign", "digest", "signatures", "signers" ] }, "OnceApproval": { "type": "object", "properties": { "device_code": { "type": "string", "description": "Absent when the user is already being asked about this cart: keep polling the device code you were given then." }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" }, "request_id": { "type": "string", "description": "Read the request's state with `GET /v1/connections/requests/{id}`." } }, "required": [ "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval", "request_id" ], "description": "On a deny for a cart over the mandate's amount or outside its merchants: the user was asked to approve this cart once. Poll `POST /v1/connections/token` with its `device_code`; the answer is a single-purchase mandate for exactly this cart." }, "CountersignRequest": { "type": "object", "properties": { "authorizationId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The PayPal authorization that holds the mandate's funds, or this request's own hold when the mandate holds each purchase separately; leg A reads it. Absent for a card mandate, whose purchase is paid with a single-use card issued after the ALLOW." }, "closedMandate": { "type": "string", "minLength": 1, "maxLength": 131072, "description": "The open mandate closed by the agent's key binding over the request and cart. Required, except of an app acting for a user under a mandate of Keelson's hosted operator, which sends `mandateId` instead." }, "mandateId": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Only for an app acting for a user (`purchases:write`) under a mandate of Keelson's hosted operator that the user approved for it: Keelson closes the mandate with the hosted operator's key over `requestId` and this cart." }, "requestId": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "With `mandateId`: the request ULID the closed mandate binds, and the purchase's id; a new one when left out." }, "cart": { "$ref": "#/components/schemas/Cart" }, "unit": { "type": "object", "additionalProperties": {}, "description": "The PayPal purchase unit the cart is checked against: `{amount}`, the checkout total the buyer pays as a PayPal Orders v2 amount, whose `breakdown` has the `item_total` of the cart's lines and, when the checkout charges them, `tax_total`, `shipping` and `discount`. Keelson countersigns `amount.value`, which must be `item_total + tax_total + shipping − discount`, and checks it against the mandate's budget. `handling`, `insurance` and `shipping_discount` are refused: fold them into `shipping`." }, "evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 8 }, "default": {}, "description": "Evidence sources per field. `channel3:` sources are refused here: the API adds them from the observation stored in the evidence." }, "evidenceRoot": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The root of the evidence stored with `POST /v1/evidence` for this mandate." }, "live": { "type": "object", "properties": { "store": { "type": "string", "maxLength": 256, "format": "uri", "description": "The store's origin: the origin of the website the mandate allows for the cart's merchant." } }, "required": [ "store" ], "additionalProperties": false, "description": "Only when the buyer pays at the store's own checkout with their own PayPal account: Keelson countersigns and logs the purchase and issues its Alibi, and neither covers nor captures it. Its Alibi is public once the PayPal transaction is recorded. The agent's pay click waits for an ALLOW; the agent then records PayPal's transaction id with `PUT /v1/purchases/{id}/paypal-transaction`." }, "repeatOf": { "type": "string", "minLength": 26, "maxLength": 26, "description": "Only when the user asked to buy the same cart again: the id of the latest purchase of this cart under the mandate. Not needed once that purchase was denied or failed before capture, or was captured more than ten minutes ago. A retry after a lost answer never sends it: the `409 purchase-exists` answer names the purchase already made." } }, "required": [ "cart", "unit", "evidenceRoot" ] }, "LivePurchase": { "type": "object", "properties": { "id": { "type": "string", "description": "The purchase and its Alibi's id." }, "store": { "type": [ "string", "null" ], "description": "The store's origin; `null` for a card purchase, named by the card network." }, "merchant": { "type": "string" }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" }, "breakdown": { "$ref": "#/components/schemas/CheckoutBreakdown" } }, "required": [ "currency", "minor" ] }, "decision": { "type": "string", "enum": [ "allow", "deny" ] }, "transactionId": { "type": [ "string", "null" ], "description": "The PayPal transaction the store was paid by; `null` for a DENY." }, "conversion": { "$ref": "#/components/schemas/Conversion" }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "For a DENY, the mandate fields whose check failed, or leg A's reason when it denied on its read of the PayPal hold." }, "card": { "type": "object", "properties": { "lastFour": { "type": "string" }, "merchantName": { "type": [ "string", "null" ] }, "mcc": { "type": [ "string", "null" ] }, "approved": { "type": "integer" }, "declined": { "type": "integer" }, "settledMinor": { "type": [ "string", "null" ] } }, "required": [ "lastFour", "merchantName", "mcc", "approved", "declined", "settledMinor" ], "description": "A card purchase: the merchant as the card network named it, and how many of the card's authorizations both legs approved and declined." }, "logIndex": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "store", "merchant", "amount", "decision", "transactionId", "blocked", "logIndex", "createdAt" ] }, "Conversion": { "type": "object", "properties": { "v": { "type": "string", "enum": [ "keelson.conversion/1" ] }, "merchant": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "value": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" } }, "required": [ "currency", "value" ] }, "buyer": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "value": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" } }, "required": [ "currency", "value" ] }, "rate": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "reference": { "type": "object", "properties": { "rate": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "provider": { "type": "string", "maxLength": 64 }, "source": { "type": "string", "maxLength": 256 }, "as_of": { "type": "string", "maxLength": 40 } }, "required": [ "rate", "provider", "source", "as_of" ] }, "spread_bps": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "max_spread_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "locale": { "type": "string", "maxLength": 35 } }, "required": [ "v", "merchant", "buyer", "rate", "reference", "spread_bps", "max_spread_bps", "locale" ], "additionalProperties": false, "description": "When PayPal converted the charge to the buyer's currency: what the buyer paid at PayPal's rate, the reference rate and the spread, as the pay-click gate checked them. Reported by the agent; its Alibi verifies the arithmetic." }, "Purchase": { "type": "object", "properties": { "id": { "type": "string" }, "mandateId": { "type": "string" }, "mode": { "type": [ "string", "null" ], "enum": [ "2of2", "degraded", null ] }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" }, "breakdown": { "$ref": "#/components/schemas/CheckoutBreakdown" } }, "required": [ "currency", "minor" ] }, "state": { "type": "string" }, "logIndex": { "type": "string", "description": "The leaf's index in the Alibi log." }, "coverage": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": [ "string", "null" ] } }, "required": [ "chainId", "txHash" ], "description": "The `lockCoverage` transaction of the operator's bond." }, "capture": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "invoiceId", "status" ], "description": "The PayPal capture of the countersigned amount." }, "failure": { "type": "object", "properties": { "step": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "step", "reason" ], "description": "The step that failed and why; nothing was captured." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "For a `DENIED` cart, the mandate fields whose check failed." }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] } }, "required": [ "field", "mandate", "cart" ] }, "description": "For a `DENIED` cart, each failed field with what the mandate allowed and what the cart had, as text." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "mandate": { "type": [ "string", "null" ] }, "cart": { "type": [ "string", "null" ] }, "pass": { "type": "boolean" } }, "required": [ "field", "mandate", "cart", "pass" ] }, "description": "For a purchase the engine checked, each mandate field with what the mandate allowed, what the cart had and whether it held." }, "card": { "type": "object", "properties": { "issuer": { "type": "string" }, "lastFour": { "type": "string" }, "state": { "type": "string" }, "expiresAt": { "type": "string" }, "controls": { "type": "object", "additionalProperties": {} }, "settledMinor": { "type": [ "string", "null" ] }, "chargebacks": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Chargebacks filed through the card issuer over this purchase." }, "bondClaimMinor": { "type": "string", "description": "The most a bond claim over this purchase may pay: the settled amount less what chargebacks returned; 0 while one is open." }, "authorizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amountMinor": { "type": "string" }, "currency": { "type": "string" }, "mcc": { "type": "string" }, "merchantName": { "type": "string" }, "merchantCountry": { "type": "string" }, "approved": { "type": "boolean" }, "failedMask": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "legs": { "type": "object", "properties": { "tdx": { "type": "boolean" }, "nitro": { "type": "boolean" } }, "required": [ "tdx", "nitro" ] }, "latencyMs": { "type": "integer" }, "at": { "type": "string" } }, "required": [ "id", "amountMinor", "currency", "mcc", "merchantName", "merchantCountry", "approved", "failedMask", "reason", "legs", "latencyMs", "at" ] } } }, "required": [ "issuer", "lastFour", "state", "expiresAt", "controls", "settledMinor", "chargebacks", "bondClaimMinor", "authorizations" ], "description": "A card purchase: its single-use card (never its number) and every authorization the card network sent it, with both legs' decision. `CAPTURED` once the merchant's capture settles." }, "live": { "type": "object", "properties": { "store": { "type": "string" }, "transactionId": { "type": [ "string", "null" ] } }, "required": [ "store", "transactionId" ], "description": "A purchase the buyer pays at the store's own checkout: the store's origin and the PayPal transaction id once the agent recorded it. Never covered nor captured." } }, "required": [ "id", "mandateId", "mode", "amount", "state" ] }, "PayPalTransaction": { "type": "object", "properties": { "transactionId": { "type": "string", "pattern": "^[0-9A-Z]{17}$", "description": "PayPal's 17-character transaction id." }, "order": { "type": "object", "properties": { "intent": { "type": "string", "enum": [ "SALE", "AUTHORIZE" ] }, "payee": { "type": "string", "pattern": "^[0-9A-Z]{8,20}$" } }, "required": [ "intent", "payee" ], "description": "PayPal's order as its checkout stated it right before the pay click: its intent and its only payee's merchant id." }, "conversion": { "allOf": [ { "$ref": "#/components/schemas/Conversion" }, { "description": "When PayPal converted the charge to the buyer's currency: the conversion as the pay-click gate checked it. It must be the countersigned amount at PayPal's rate, use the reference rate the evidence binds, and be within the mandate's `fx.max_spread_bps`." } ] } }, "required": [ "transactionId" ] }, "PurchaseCard": { "type": "object", "properties": { "lastFour": { "type": "string" }, "expiresAt": { "type": "string" }, "embedUrl": { "type": "string" } }, "required": [ "lastFour", "expiresAt", "embedUrl" ] }, "EvidenceUpload": { "type": "object", "properties": { "mandateId": { "type": "string", "minLength": 26, "maxLength": 26 }, "manifest": { "$ref": "#/components/schemas/EvidenceManifest" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 64 }, "mediaType": { "type": "string", "maxLength": 128 }, "salt": { "type": "string", "description": "32 random bytes, base64." }, "bytes": { "type": "string", "description": "The item bytes, base64." } }, "required": [ "type", "mediaType", "salt", "bytes" ] }, "minItems": 1, "maxItems": 26 } }, "required": [ "mandateId", "manifest", "items" ] }, "EvidenceManifest": { "type": "object", "properties": { "v": { "type": "string", "enum": [ "keelson.manifest/1" ] }, "root": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "media_type": { "type": "string" }, "leaf": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "`SHA-256(0x00 ‖ \"keelson/evidence-item/v1\" ‖ salt ‖ type ‖ 0x00 ‖ media_type ‖ 0x00 ‖ content_hash)`." } }, "required": [ "type", "media_type", "leaf" ] }, "minItems": 1, "maxItems": 26 } }, "required": [ "v", "root", "items" ], "description": "Type, media type and salted leaf of every item, in order; `root` is the RFC 6962 tree hash of the leaves and the `evidenceRoot`. Content hashes and salts are only given in a disclosure." }, "DisclosedEvidence": { "type": "object", "properties": { "disclosure": { "$ref": "#/components/schemas/EvidenceDisclosure" }, "bytes": { "type": "string" } }, "required": [ "disclosure", "bytes" ] }, "EvidenceDisclosure": { "type": "object", "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "media_type": { "type": "string" }, "content_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "salt": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "path": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "description": "The RFC 9162 inclusion proof, leaf first." }, "size": { "type": "integer" } }, "required": [ "index", "type", "media_type", "content_hash", "salt", "path", "size" ] }, "Channel3Observation": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "unavailable" ], "description": "`unavailable` when Channel3 did not answer in time or failed; it is stored too." }, "item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "channel3.observation" ] }, "mediaType": { "type": "string", "enum": [ "application/json" ] }, "salt": { "type": "string", "description": "32 random bytes, base64." }, "bytes": { "type": "string", "description": "The JCS observation document, base64." }, "content_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "leaf": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "type", "mediaType", "salt", "bytes", "content_hash", "leaf" ], "description": "The sealed evidence item to add to the capture's items, after `har`, before `buildManifest` and `POST /v1/evidence`." }, "comparison": { "$ref": "#/components/schemas/Channel3Comparison" } }, "required": [ "id", "status", "item", "comparison" ] }, "Channel3Comparison": { "type": "object", "properties": { "offerDomain": { "type": [ "string", "null" ] }, "variant": { "type": "string", "enum": [ "match", "mismatch", "unknown" ] }, "price": { "type": "string", "enum": [ "match", "mismatch", "unknown" ] }, "availability": { "type": "string", "enum": [ "match", "mismatch", "unknown" ] }, "brand": { "type": "string", "enum": [ "match", "mismatch", "unknown" ] }, "mismatches": { "type": "array", "items": { "type": "string" } } }, "required": [ "offerDomain", "variant", "price", "availability", "brand", "mismatches" ] }, "Channel3ObservationRequest": { "type": "object", "properties": { "mandateId": { "type": "string", "minLength": 26, "maxLength": 26 }, "url": { "type": "string", "maxLength": 2048, "description": "The product page the agent is on." }, "agentView": { "type": "object", "properties": { "contentHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The `content_hash` of the capture's `api.product` item the view was read from." }, "brand": { "type": "string", "minLength": 1, "maxLength": 256 }, "priceMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$", "description": "The price the agent saw, in minor units." }, "currency": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ] }, "available": { "type": "boolean" }, "selected": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "label": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name", "label" ] }, "maxItems": 16 } }, "required": [ "contentHash", "priceMinor", "currency", "available", "selected" ], "description": "What the agent saw on the page." } }, "required": [ "mandateId", "url", "agentView" ] }, "FxReference": { "type": "object", "properties": { "v": { "type": "string", "enum": [ "keelson.fx_reference/1" ] }, "provider": { "type": "string" }, "source": { "type": "string" }, "base": { "type": "string" }, "as_of": { "type": "string", "description": "When the provider last updated the rates." }, "fetched_at": { "type": "string" }, "rates": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Units of each currency one unit of `base` buys, as decimal strings." } }, "required": [ "v", "provider", "source", "base", "as_of", "fetched_at", "rates" ] }, "WebFact": { "type": "object", "properties": { "webFact": { "type": "object", "properties": { "web_fact": { "type": "object", "properties": { "hostHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "urlPathHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "tCapture": { "type": "integer" }, "rangeCommitment": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "attId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "hostHash", "urlPathHash", "tCapture", "rangeCommitment", "attId" ] }, "chain_id": { "type": "integer" }, "digest": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "signature": { "type": "string" }, "signer": { "type": "string" } }, "required": [ "web_fact", "chain_id", "digest", "signature", "signer" ] }, "mode": { "type": "string", "enum": [ "mpc", "proxy" ] }, "ms": { "type": "integer", "description": "How long the TLSNotary session took." }, "range": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "description": "The committed range of the response, `[start, end)`." }, "committed": { "type": "string", "description": "The committed bytes, hex." }, "blinder": { "type": "string", "description": "The 16-byte blinder, hex: `rangeCommitment` is `SHA-256(committed ‖ blinder)`." } }, "required": [ "webFact", "mode", "ms", "range", "committed", "blinder" ] }, "WebFactRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 1024, "description": "A public JSON product endpoint, such as a Shopify store's `/products/.js`." }, "anchor": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Commit to the smallest JSON object in the body that contains this text (a variant's `\"id\":123`) instead of the whole body." } }, "required": [ "url" ] }, "CardChargeback": { "type": "object", "properties": { "id": { "type": "string" }, "purchaseId": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_received", "not_as_described", "unauthorized" ] }, "networkCodes": { "type": "object", "properties": { "visa": { "type": "string" }, "mastercard": { "type": "string" } }, "required": [ "visa", "mastercard" ] }, "amountMinor": { "type": "string" }, "status": { "type": "string" }, "resolution": { "type": [ "string", "null" ] }, "recoveredMinor": { "type": [ "string", "null" ] }, "evidenceUploaded": { "type": "boolean" } }, "required": [ "id", "purchaseId", "reason", "networkCodes", "amountMinor", "status", "resolution", "recoveredMinor", "evidenceUploaded" ] }, "TeeLeg": { "type": "object", "properties": { "tee": { "type": "string", "enum": [ "tdx", "nitro" ] }, "signer": { "type": "string" }, "measurement": { "type": "string" }, "registeredAt": { "type": "string" }, "verifiedAt": { "type": "string", "description": "When the attestation last verified." }, "expiresAt": { "type": "string" }, "onchain": { "type": [ "object", "null" ], "properties": { "chainId": { "type": "number" }, "verdictVerifier": { "type": "string" }, "registeredAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "chainId", "verdictVerifier", "registeredAt", "expiresAt" ], "description": "The signer's record in the VerdictVerifier, which on-chain verification reads; null when it is not registered there." }, "attestation": { "type": "object", "additionalProperties": {}, "description": "The attestation the signer was admitted from: the platform evidence, its binding and the block it was made over." } }, "required": [ "tee", "signer", "measurement", "registeredAt", "verifiedAt", "expiresAt", "onchain", "attestation" ] }, "Timestamp": { "type": "object", "properties": { "tsa": { "type": "string", "enum": [ "digicert", "sigstore", "freetsa", "sectigo" ] }, "role": { "type": "string", "enum": [ "primary", "fallback" ] }, "token": { "type": "string", "description": "The DER `TimeStampToken`, base64." }, "genTime": { "type": "string", "description": "The token's `genTime`, RFC 3339 UTC." }, "serial": { "type": "string", "description": "The token's serial number, hex." } }, "required": [ "tsa", "role", "token", "genTime", "serial" ] }, "AlibiReport": { "type": "object", "properties": { "reference": { "type": "string" }, "verdict": { "type": "string", "enum": [ "verified", "verified-unanchored", "verified-offline", "failed", "incomplete" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "step": { "type": "integer" }, "status": { "type": "string", "enum": [ "pass", "fail", "undisclosed", "pending", "absent", "unreachable" ] }, "reason": { "type": "string" }, "reads": { "type": "array", "items": { "type": "string" }, "description": "RFC 6901 pointers the check read." }, "ms": { "type": "number" }, "detail": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "step", "status", "reads", "ms" ] } }, "mode": { "type": "string", "enum": [ "2of2", "degraded" ] }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "unbound": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string" }, "value": {} }, "required": [ "pointer" ] } }, "changed": { "type": "array", "items": { "type": "string" } }, "rpc": { "type": "object", "properties": { "url": { "type": "string" }, "custom": { "type": "boolean" } }, "required": [ "url", "custom" ] }, "ms": { "type": "number" } }, "required": [ "reference", "verdict", "checks", "mode", "fields", "unbound", "changed", "ms" ] }, "AlibiReceipt": { "type": "object", "properties": { "alibi_id": { "type": "string" }, "leaf": { "type": "string", "description": "The leaf bytes, base64." }, "leaf_hash": { "type": "string", "description": "The RFC 6962 leaf hash, unpadded base64url." }, "tlog_proof": { "type": "string", "description": "A c2sp.org/tlog-proof@v1 with cosignatures." }, "anchor": { "type": "object", "additionalProperties": {} }, "timestamps": { "type": "array", "items": { "type": "object", "properties": { "tsa": { "type": "string" }, "token": { "type": "string" } }, "required": [ "tsa", "token" ] } } }, "required": [ "alibi_id", "leaf", "leaf_hash", "tlog_proof", "timestamps" ] }, "AnonymousMandate": { "type": "object", "properties": { "mandate_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The passkey challenge `M` the user signed." }, "mandate_commitment": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "`C_m`, the commitment the mandate names." }, "user_set_root": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The registered-user tree the signer is a leaf of when the proof was made." }, "proof": { "type": "string", "description": "The UltraHonk proof bytes, standard base64." }, "public_inputs": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "description": "`C_m, M mod r, user_set_root, SHA-256(\"keelson.finance\")`: the calldata of `verify(bytes,bytes32[])`." }, "verifier": { "type": "object", "properties": { "chain_id": { "type": "integer" }, "address": { "type": "string" } }, "required": [ "chain_id", "address" ], "description": "The deployed verifier that accepts the proof in an `eth_call`. It checks the proof only: `public_inputs` must also be the countersign's `C_m` and `M`, Keelson's RP ID hash, and a root published in `RegisteredUserSet`, whose `verify` checks all of it." } }, "required": [ "mandate_hash", "mandate_commitment", "user_set_root", "proof", "public_inputs" ] }, "AnonymousPurchase": { "type": "object", "properties": { "user_set_root": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "proof": { "type": "string", "description": "The UltraHonk proof bytes, standard base64." }, "public_inputs": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "description": "C1's `C_m, amount, currency, category, merchant_id, now, cart_hash, operator_id`, then `M mod r` and `user_set_root`: the calldata of `verify(bytes,bytes32[])`." }, "verifier": { "type": "object", "properties": { "chain_id": { "type": "integer" }, "address": { "type": "string" } }, "required": [ "chain_id", "address" ], "description": "The deployed verifier that accepts the proof in an `eth_call`. It checks the proof only: `public_inputs` must also be the countersign's and the root one `GET /v1/user-set/roots/{root}` lists." }, "root_tx": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The Arbitrum Sepolia transaction that published `user_set_root` to `RegisteredUserSet`, once it is confirmed." } }, "required": [ "user_set_root", "proof", "public_inputs" ] }, "UserSetRoot": { "type": "object", "properties": { "root": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "size": { "type": "integer", "description": "Registered users when the tree had this root." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "root", "size", "created_at" ] }, "EngineProof": { "type": "object", "properties": { "purchase_id": { "type": "string" }, "status": { "type": "string", "enum": [ "proven", "proving", "failed" ], "description": "`proving`: the purchase is disputed and its proof is being made. `proven`: the proof is recorded on chain. `failed`: no proof was recorded within the workflow's time, retries included." }, "countersign_eval_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The `evalHash` both TEE legs signed." }, "countersign_digest": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The EIP-712 digest of their countersign." }, "proof": { "type": [ "object", "null" ], "properties": { "eval_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The `evalHash` the engine program computed in the SP1 zkVM." }, "matches": { "type": "boolean", "description": "Whether `eval_hash` is the countersign's and the proof is of its digest." }, "public_values": { "type": "string", "description": "`abi.encode(evalHash, countersignDigest)`." }, "proof": { "type": "string", "description": "The SP1 Groth16 proof bytes, hex." }, "vkey": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The engine program's SP1 verifying key." }, "sp1_version": { "type": "string" }, "cycles": { "type": "integer" }, "prove_ms": { "type": "integer" }, "proof_bytes": { "type": "integer" }, "verifier": { "type": "object", "properties": { "chain_id": { "type": "integer" }, "address": { "type": "string" } }, "required": [ "chain_id", "address" ], "description": "The `EngineProofVerifier` that verified the proof through Succinct's SP1 verifier gateway; `verify(public_values, proof)` checks it again in an `eth_call`, `proven(countersign_digest)` returns the recorded `eval_hash`." }, "tx": { "type": "string", "description": "The `EngineProofVerifier.record` transaction." }, "explorer_url": { "type": [ "string", "null" ] }, "gas_used": { "type": "string" }, "proven_at": { "type": "string", "format": "date-time" } }, "required": [ "eval_hash", "matches", "public_values", "proof", "vkey", "sp1_version", "cycles", "prove_ms", "proof_bytes", "verifier", "tx", "explorer_url", "gas_used", "proven_at" ] } }, "required": [ "purchase_id", "status", "countersign_eval_hash", "countersign_digest", "proof" ] }, "DisputeStatus": { "type": "object", "properties": { "dispute_id": { "type": "string" }, "purchase_id": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ATTRIBUTED", "RESOLVED" ] }, "reason": { "type": "string", "description": "PayPal's `dispute_reason`." }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Keelson received the dispute's first webhook or poll." }, "attributed_at": { "type": [ "string", "null" ], "format": "date-time" }, "elapsed_ms": { "type": [ "integer", "null" ], "description": "From `received_at` to `attributed_at`; null while the dispute is open." }, "liable": { "type": [ "string", "null" ], "enum": [ "operator", "keelson", "merchant", "user", null ] }, "parties": { "type": "array", "items": { "type": "object", "properties": { "party": { "type": "string", "enum": [ "operator", "keelson", "merchant" ] }, "liable": { "type": "boolean" } }, "required": [ "party", "liable" ] }, "description": "The parties a verdict can make pay: the operator's bond, Keelson's reserve, or the merchant through PayPal." }, "verdict": { "type": [ "object", "null" ], "properties": { "rule": { "type": "string", "example": "R61" }, "digest": { "type": "string" }, "chain_id": { "type": "integer" }, "message": { "type": "object", "additionalProperties": { "type": "string" } }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "tee": { "type": "integer" }, "signer": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "tee", "signer", "signature" ] } }, "facts": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } } }, "required": [ "rule", "digest", "chain_id", "message", "signatures", "facts" ] }, "settlement": { "type": [ "object", "null" ], "properties": { "rail": { "type": "string", "enum": [ "pyusd", "paypal" ], "description": "`pyusd`: the payee the verdict names is the merchant. `paypal`: it is Keelson's treasury, which pays the merchant a PayPal Payout." }, "outcome": { "type": [ "string", "null" ], "enum": [ "paid", "queued", "claimable", "failed", null ], "description": "`queued`: the slash waits out the veto window until `ready_at`. `claimable`: the PYUSD transfer failed and waits as a claim. Null until the chain answered; always null when neither the operator nor Keelson is liable." }, "failure": { "type": [ "string", "null" ], "description": "The contract error that refused the settlement on chain: of a `failed` one, or of one Keelson's treasury paid instead." }, "paid_by": { "type": [ "string", "null" ], "enum": [ "chain", "treasury", "violation-pool", null ], "description": "`chain`: the operator's bond or Keelson's reserve paid. `violation-pool`: the operator's `ViolationBondPool` deposit paid the merchant on a court's conviction, with no verdict. `treasury`: the chain refused a verdict that still holds (its window or deadline had passed), so Keelson's treasury pays the payee itself, PYUSD on chain or a PayPal Payout; the settlement is paid once `outcome` is `paid`." }, "refund_id": { "type": [ "string", "null" ], "description": "The buyer's PayPal refund; its `custom_id` is the verdict's `ksv1.` reference." }, "tx_hash": { "type": [ "string", "null" ] }, "explorer_url": { "type": [ "string", "null" ] }, "ready_at": { "type": [ "string", "null" ], "format": "date-time" }, "payout_batch_id": { "type": [ "string", "null" ] }, "payout_status": { "type": [ "string", "null" ] }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "rail", "outcome", "failure", "paid_by", "refund_id", "tx_hash", "explorer_url", "ready_at", "payout_batch_id", "payout_status", "settled_at" ] }, "responses": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "provide_evidence", "send_message", "accept_claim" ] }, "stage": { "type": "string", "description": "PayPal's lifecycle stage when it was sent." }, "evidence_types": { "type": "array", "items": { "type": "string" } }, "drafted_by": { "type": [ "string", "null" ], "enum": [ "model", "template", null ], "description": "`model` when the statement was drafted with citations; `template` when the rule's fixed statement was sent. Null for an accepted claim." }, "citations": { "type": "integer", "description": "How many passages of the Alibi and the verdict the statement cites. The statement itself is not public: it quotes the purchase's Alibi." }, "sent_at": { "type": "string", "format": "date-time" } }, "required": [ "action", "stage", "evidence_types", "drafted_by", "citations", "sent_at" ] }, "description": "What Keelson sent PayPal for the party at fault. The action and the evidence types follow from the rule; a model only drafts the text." }, "amber": { "$ref": "#/components/schemas/AmberCase" } }, "required": [ "dispute_id", "purchase_id", "state", "reason", "received_at", "attributed_at", "elapsed_ms", "liable", "parties", "verdict", "settlement", "responses", "amber" ] }, "AmberCase": { "type": [ "object", "null" ], "properties": { "commitment": { "type": "string", "pattern": "^0x[0-9a-f]+$", "description": "The `amberCommitment` the operator signed into the coverage: Poseidon2 over the product page, the fields below and a salt." }, "attested": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The store's JSON page for the SKU." }, "sku": { "type": "string" }, "size": { "type": "string" }, "color": { "type": "string" }, "unit_minor": { "type": "string", "pattern": "^\\d+$" }, "returns_free": { "type": "boolean" } }, "required": [ "url", "sku", "size", "color", "unit_minor", "returns_free" ], "description": "What the operator attested. Null on the public dispute read: what was bought stays with the consoles." }, "conviction": { "type": [ "object", "null" ], "properties": { "field": { "type": "string", "enum": [ "size", "color", "unit_price", "returns_free" ] }, "attested_value": { "type": [ "string", "null" ], "description": "What the operator attested of the field, which the store's answer contradicts. Null on the public dispute read." }, "proven_at": { "type": "string", "format": "date-time" }, "web_fact_digest": { "type": "string", "pattern": "^0x[0-9a-f]+$", "description": "The EIP-712 digest of the `WebFact` leg A signed over the store's answer." }, "captured_at": { "type": [ "string", "null" ], "format": "date-time" }, "tx_hash": { "type": "string", "pattern": "^0x[0-9a-f]+$" }, "explorer_url": { "type": "string", "format": "uri" }, "proof": { "type": [ "object", "null" ], "properties": { "bytes": { "type": "integer" }, "hash": { "type": "string", "pattern": "^0x[0-9a-f]+$", "description": "keccak256 of the proof." }, "public_inputs": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-f]+$" }, "description": "`range_hi, range_lo, amber_commitment, product, field_id`, as the court gave the verifier." } }, "required": [ "bytes", "hash", "public_inputs" ] } }, "required": [ "field", "attested_value", "proven_at", "web_fact_digest", "captured_at", "tx_hash", "explorer_url", "proof" ], "description": "`AmberContradictionCourt`'s conviction on Arbitrum Sepolia: a C2b proof that the store's own answer, notarized by leg A, holds another value of `field`. Null while there is none." } }, "required": [ "commitment", "attested", "conviction" ], "description": "What the operator attested about the item it bought, and whether it was proven false. Null when the purchase carries no attestation (a cart of several lines, or bought before attestations)." }, "Passkeys": { "type": "object", "properties": { "passkeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "credentialId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "payment": { "type": "boolean", "description": "Registered with the SPC `payment` extension, so SPC can use it." } }, "required": [ "id", "credentialId", "name", "createdAt", "payment" ] } } }, "required": [ "passkeys" ] }, "Operator": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "chainId": { "type": "integer" }, "agentRegistry": { "type": "string" }, "owner": { "type": "string", "description": "The agent's owner in the Identity registry." } }, "required": [ "agentId", "chainId", "agentRegistry", "owner" ] }, "LinkOperator": { "type": "object", "properties": { "chainId": { "anyOf": [ { "type": "number", "enum": [ 421614 ] }, { "type": "number", "enum": [ 42161 ] }, { "type": "number", "enum": [ 11155111 ] } ] }, "agentId": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cnfJwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "EC" ] }, "crv": { "type": "string", "enum": [ "P-256" ] }, "x": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "y": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kid": { "type": "string", "maxLength": 64 } }, "required": [ "kty", "crv", "x", "y" ], "description": "The agent's P-256 `cnf` key, a public JWK." }, "deadline": { "type": "integer", "exclusiveMinimum": 0, "description": "Unix seconds, at most 15 minutes ahead." }, "signature": { "type": "string", "maxLength": 8194, "pattern": "^0x([0-9a-fA-F]{2})+$", "description": "The EIP-712 `OperatorLink(uint256 agentId,bytes32 cnfThumbprint,uint256 deadline)` signature under the domain `{ name: \"Keelson\", version: \"1\", chainId }`, by the agent's owner or `agentWallet` (EOA, ERC-1271 or ERC-6492). `cnfThumbprint` is the RFC 7638 SHA-256 thumbprint of `cnfJwk`." } }, "required": [ "chainId", "agentId", "name", "cnfJwk", "deadline", "signature" ] }, "AgentRegistration": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "endpoint" ] } }, "x402Support": { "type": "boolean" }, "active": { "type": "boolean" }, "registrations": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "agentRegistry": { "type": "string" } }, "required": [ "agentId", "agentRegistry" ] } }, "supportedTrust": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "description", "image", "services", "x402Support", "active", "registrations" ], "description": "An ERC-8004 agent registration file (`registration-v1`)." }, "OperatorBond": { "type": "object", "properties": { "bond": { "type": "object", "properties": { "free": { "type": "string" }, "locked": { "type": "string" }, "queued": { "type": "string" }, "slashCount": { "type": "integer" } }, "required": [ "free", "locked", "queued", "slashCount" ] }, "reputation": { "type": "object", "properties": { "count": { "type": "integer" }, "value": { "type": "string", "description": "The average feedback value, fixed-point." }, "decimals": { "type": "integer" }, "slashes": { "type": "integer" } }, "required": [ "count", "value", "decimals", "slashes" ] }, "validation": { "type": "object", "properties": { "count": { "type": "integer" }, "averageResponse": { "type": "integer" } }, "required": [ "count", "averageResponse" ] } }, "required": [ "bond", "reputation", "validation" ], "description": "The operator's bond in PYUSD base units, the Keelson feedback it has in the ERC-8004 Reputation registry, and the TEE countersigns recorded for it in the Keelson validation registry." }, "OperatorMandate": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "ACTIVE" ] }, "currency": { "type": "string" }, "maxMinor": { "type": "integer" }, "remainingMinor": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" }, "holdMode": { "type": [ "string", "null" ], "enum": [ "mandate", "per_purchase", null ] }, "authorizationId": { "type": [ "string", "null" ], "description": "The PayPal authorization that holds the mandate's funds, when the mandate is held as a whole." }, "openMandate": { "type": "string", "description": "The mandate as issued, which the agent closes with its `cnf` key for each countersign." } }, "required": [ "id", "state", "currency", "maxMinor", "remainingMinor", "expiresAt", "holdMode", "authorizationId", "openMandate" ] }, "AgentRun": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "started", "ended" ] }, "liveViewUrl": { "type": "string", "format": "uri", "description": "Kernel's live view of the agent's browser, opened read-only." } }, "required": [ "state" ] }, "TrustGrade": { "type": "object", "properties": { "v": { "type": "string", "enum": [ "keelson.grade/1" ] }, "agentId": { "type": "string" }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ], "description": "From the one-sided 95 % credible upper bound of the incident rate: A ≤ 1 %, B ≤ 2 %, C ≤ 5 %, D ≤ 10 %, F above." }, "computedAt": { "type": "string", "format": "date-time" }, "calibration": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "campaigns": { "type": "array", "items": { "type": "string" }, "description": "The red-team campaigns pooled." }, "mu_ppm": { "type": "integer", "description": "The prior's mean, ASR × escape + amber." }, "kappa": { "type": "number", "description": "The prior's strength, by the method of moments." } }, "required": [ "id", "at", "campaigns", "mu_ppm", "kappa" ] }, "evidence": { "type": "object", "properties": { "coverages": { "type": "integer" }, "incidents": { "type": "object", "properties": { "total": { "type": "integer" }, "slashes": { "type": "integer", "description": "Paid from the operator's bond." }, "pool": { "type": "integer", "description": "Paid from its `ViolationBondPool` deposit." }, "uncollected": { "type": "integer", "description": "Paid by Keelson's treasury instead." }, "pending": { "type": "integer", "description": "Not settled yet." } }, "required": [ "total", "slashes", "pool", "uncollected", "pending" ], "description": "Verdicts with the operator at fault: what the grade counts." } }, "required": [ "coverages", "incidents" ] }, "reserve": { "type": "object", "properties": { "warranties": { "type": "integer" } }, "required": [ "warranties" ], "description": "Keelson's own faults on the operator's coverages, paid by its reserve. Not in the grade." }, "frequency": { "type": "object", "properties": { "alpha": { "type": "number" }, "beta": { "type": "number" }, "credibility_ppm": { "type": "integer" }, "mean_ppm": { "type": "integer" }, "upper95_ppm": { "type": "integer" } }, "required": [ "alpha", "beta", "credibility_ppm", "mean_ppm", "upper95_ppm" ] }, "severity": { "type": "object", "properties": { "meanMinor": { "type": "integer" }, "maxMinor": { "type": "integer" }, "lossRatio_ppm": { "type": "integer" } }, "required": [ "meanMinor", "maxMinor", "lossRatio_ppm" ] }, "loss": { "type": "object", "properties": { "horizon": { "type": "integer" }, "scenarios": { "type": "integer" }, "expectedMinor": { "type": "integer" }, "var99Minor": { "type": "integer" }, "es99Minor": { "type": "integer" }, "var995Minor": { "type": "integer" } }, "required": [ "horizon", "scenarios", "expectedMinor", "var99Minor", "es99Minor", "var995Minor" ] }, "premium": { "type": "object", "properties": { "bps": { "type": "integer", "description": "Charged on each new coverage, in `lockCoverage`." }, "modelBps": { "type": "integer" }, "floorBps": { "type": "integer" }, "theta": { "type": "number" }, "costOfCapital": { "type": "number" } }, "required": [ "bps", "modelBps", "floorBps", "theta", "costOfCapital" ] }, "bond": { "type": "object", "properties": { "requiredMinor": { "type": "integer" } }, "required": [ "requiredMinor" ] }, "computeMs": { "type": "number" } }, "required": [ "v", "agentId", "grade", "computedAt", "calibration", "evidence", "reserve", "frequency", "severity", "loss", "premium", "bond", "computeMs" ], "description": "An operator's trust grade, premium and minimum bond. Amounts are US cents. The red-team campaigns set the prior of the incident rate; the operator's covered purchases and the verdicts with it at fault update it in closed form; a seeded Monte Carlo of the aggregate loss over the next 30 days prices the premium and the bond." }, "Feedback": { "type": "object", "properties": { "agentRegistry": { "type": "string" }, "agentId": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "clientAddress": { "type": "string", "description": "The reporter, as a CAIP-10 account." }, "createdAt": { "type": "string" }, "value": { "type": "integer" }, "valueDecimals": { "type": "integer" }, "tag1": { "type": "string" }, "tag2": { "type": "string" }, "keelson": { "type": "object", "properties": { "coverageId": { "type": "string" }, "txHash": { "type": "string" } }, "required": [ "coverageId", "txHash" ] } }, "required": [ "agentRegistry", "agentId", "clientAddress", "createdAt", "value", "valueDecimals", "tag1", "tag2", "keelson" ], "description": "An ERC-8004 off-chain feedback file." }, "ValidationRequest": { "type": "object", "properties": { "payload": { "type": "string", "description": "`0x1901 ‖ domainSeparator ‖ hashStruct(Countersign)`; its keccak256 is the request hash." }, "countersign": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The EIP-712 `Countersign` message, as decimal strings." }, "alibi": { "type": "string", "description": "The purchase's Alibi, once logged." } }, "required": [ "payload", "countersign" ], "description": "The data of an ERC-8004 validation request Keelson records for a countersign." }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "chainId": { "type": "integer" }, "key": { "type": "string", "description": "`.:`." }, "contract": { "type": "string" }, "functionName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "reverted", "rejected", "dropped" ] }, "hash": { "type": "string" }, "nonce": { "type": "string" }, "blockNumber": { "type": "string" }, "blockHash": { "type": "string" }, "gasUsed": { "type": "string" }, "effectiveGasPrice": { "type": "string" }, "latencyMs": { "type": "integer" }, "errorCode": { "type": "string" }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "args": { "type": "array", "items": {} } }, "required": [ "name", "args" ] }, "explorerUrl": { "type": "string" } }, "required": [ "id", "chainId", "key", "contract", "functionName", "status" ], "description": "A transaction the Keelson relayer sent and paid for." }, "BondDeposit": { "oneOf": [ { "type": "object", "properties": { "chainId": { "anyOf": [ { "type": "number", "enum": [ 421614 ] }, { "type": "number", "enum": [ 42161 ] } ], "description": "Arbitrum Sepolia (421614) or Arbitrum One (42161)." }, "kind": { "type": "string", "enum": [ "authorization" ] }, "from": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "PYUSD base units." }, "validAfter": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds." }, "validBefore": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds." }, "salt": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The EIP-3009 nonce is `keccak256(abi.encode(agentId, salt))`, so the authorization credits only this agent." }, "signature": { "type": "string", "maxLength": 8194, "pattern": "^0x([0-9a-fA-F]{2})+$", "description": "PYUSD's EIP-3009 `ReceiveWithAuthorization` to the vault, signed by `from`." } }, "required": [ "chainId", "kind", "from", "amount", "validAfter", "validBefore", "salt", "signature" ] }, { "type": "object", "properties": { "chainId": { "anyOf": [ { "type": "number", "enum": [ 421614 ] }, { "type": "number", "enum": [ 42161 ] } ], "description": "Arbitrum Sepolia (421614) or Arbitrum One (42161)." }, "kind": { "type": "string", "enum": [ "permit" ] }, "owner": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The agent's owner or agent wallet." }, "amount": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "PYUSD base units." }, "deadline": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds." }, "signature": { "type": "string", "maxLength": 8194, "pattern": "^0x([0-9a-fA-F]{2})+$", "description": "PYUSD's EIP-2612 permit to the vault." } }, "required": [ "chainId", "kind", "owner", "amount", "deadline", "signature" ] } ] }, "BondWithdrawal": { "type": "object", "properties": { "chainId": { "anyOf": [ { "type": "number", "enum": [ 421614 ] }, { "type": "number", "enum": [ 42161 ] } ], "description": "Arbitrum Sepolia (421614) or Arbitrum One (42161)." }, "amount": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "PYUSD base units." }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "nonce": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "`vault.nonces(signer)`." }, "deadline": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds." }, "ownerSignature": { "type": "string", "maxLength": 8194, "pattern": "^0x([0-9a-fA-F]{2})+$", "description": "The vault's EIP-712 `WithdrawalRequest`, by the agent's owner or agent wallet." } }, "required": [ "chainId", "amount", "to", "nonce", "deadline", "ownerSignature" ] }, "LogBond": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "origin": { "type": "string" }, "test": { "type": "boolean", "description": "A test origin's bond, slashed by the equivocation drill." }, "key": { "type": "string", "description": "The Ed25519 log key the bond pins, hex." }, "owner": { "type": "string" }, "verifier": { "type": "string", "description": "The Ed25519 verifier the bond calls." }, "canonical": { "type": "boolean", "description": "Whether the bond calls the registry's `Ed25519Verifier` over PYUSD. A bond on another verifier or token proves nothing." }, "beneficiary": { "type": "string", "description": "Who receives a slash, less the bounty." }, "bountyBps": { "type": "number" }, "completionWindowSeconds": { "type": "number" }, "balanceMinor": { "type": "string" }, "withdrawalDelaySeconds": { "type": "number" }, "withdrawal": { "type": [ "object", "null" ], "properties": { "amountMinor": { "type": "string" }, "unlockAt": { "type": "string" }, "to": { "type": "string" } }, "required": [ "amountMinor", "unlockAt", "to" ] }, "equivocation": { "$ref": "#/components/schemas/LogEquivocation" }, "explorerUrl": { "type": "string" } }, "required": [ "chainId", "address", "origin", "test", "key", "owner", "verifier", "canonical", "beneficiary", "bountyBps", "completionWindowSeconds", "balanceMinor", "withdrawalDelaySeconds", "withdrawal", "equivocation", "explorerUrl" ] }, "LogEquivocation": { "type": [ "object", "null" ], "properties": { "prover": { "type": "string" }, "amountMinor": { "type": "string", "description": "The whole bond slashed, PYUSD base units." }, "bountyMinor": { "type": "string", "description": "The prover's bounty out of it; the rest went to the bond's beneficiary." }, "provenAt": { "type": "string" }, "size": { "type": "string", "description": "The tree size both checkpoints state." }, "rootA": { "type": "string" }, "rootB": { "type": "string" }, "noteA": { "type": [ "string", "null" ], "description": "The first signed checkpoint, as submitted; null until its transaction is found." }, "noteB": { "type": [ "string", "null" ] }, "txHash": { "type": [ "string", "null" ] }, "explorerUrl": { "type": [ "string", "null" ] } }, "required": [ "prover", "amountMinor", "bountyMinor", "provenAt", "size", "rootA", "rootB", "noteA", "noteB", "txHash", "explorerUrl" ] }, "PayoutAddress": { "type": "object", "properties": { "chainId": { "anyOf": [ { "type": "number", "enum": [ 421614 ] }, { "type": "number", "enum": [ 42161 ] } ] }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payout": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Where slashes and warranties for the merchant are paid." }, "nonce": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "`vault.nonces(merchant)`." }, "deadline": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds." }, "merchantSignature": { "type": "string", "maxLength": 8194, "pattern": "^0x([0-9a-fA-F]{2})+$", "description": "The vault's EIP-712 `PayoutAddress`, by the merchant (EOA or ERC-1271)." } }, "required": [ "chainId", "merchant", "payout", "nonce", "deadline", "merchantSignature" ] }, "SignedSettlementPreference": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "pyusd", "paypal" ], "description": "`pyusd`: slashes and warranties pay the merchant in PYUSD on chain. `paypal`: they pay Keelson's treasury, and Keelson sends the merchant a PayPal Payout in USD." }, "paypal_receiver": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "string", "pattern": "^[A-Z0-9]{13}$" } ], "description": "The PayPal account paid: an email address or a PayPal account id." }, "nonce": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Higher than the nonce of the merchant's last choice." }, "deadline": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Unix seconds after which the signature is refused." }, "merchant_signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The merchant's EIP-712 `SettlementPreference(string merchantId,string rail,string paypalReceiver,uint256 nonce,uint256 deadline)` under the bond vault's domain, by its settlement address; `paypalReceiver` is empty for `pyusd`." } }, "required": [ "rail", "nonce", "deadline", "merchant_signature" ] }, "MerchantSelf": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "settlement_address": { "type": "string", "description": "The wallet the merchant signs in and signs its choices with." }, "read_only": { "type": "boolean", "description": "True for a Judge Mode session: it reads the console and changes nothing." } }, "required": [ "merchant_id", "name", "website", "settlement_address", "read_only" ] }, "MerchantSettlement": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "pyusd", "paypal" ] }, "paypal_receiver": { "type": [ "string", "null" ] }, "nonce": { "type": "string", "description": "The nonce of the last signed choice; 0 if none." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "rail", "paypal_receiver", "nonce", "updated_at" ] }, "MerchantDispute": { "type": "object", "properties": { "dispute_id": { "type": "string" }, "purchase_id": { "type": "string", "description": "Also the id of the purchase's Alibi." }, "state": { "type": "string", "enum": [ "OPEN", "ATTRIBUTED", "RESOLVED" ] }, "reason": { "type": "string" }, "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "agent_id": { "type": "string", "description": "The ERC-8004 agent that made the purchase." }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "attributed_at": { "type": [ "string", "null" ], "format": "date-time" }, "elapsed_ms": { "type": [ "integer", "null" ] }, "liable": { "type": [ "string", "null" ], "enum": [ "operator", "keelson", "merchant", "user", null ] }, "rule": { "type": [ "string", "null" ] }, "rail": { "type": [ "string", "null" ], "enum": [ "pyusd", "paypal", null ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "paid", "queued", "claimable", "failed", null ] }, "paid_by": { "type": [ "string", "null" ], "enum": [ "chain", "treasury", "violation-pool", null ] }, "ready_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "explorer_url": { "type": [ "string", "null" ], "format": "uri" }, "has_alibi": { "type": "boolean" }, "amber": { "$ref": "#/components/schemas/AmberCase" } }, "required": [ "dispute_id", "purchase_id", "state", "reason", "amount_minor", "currency", "agent_id", "received_at", "attributed_at", "elapsed_ms", "liable", "rule", "rail", "outcome", "paid_by", "ready_at", "settled_at", "explorer_url", "has_alibi", "amber" ] }, "MerchantOrder": { "type": "object", "properties": { "purchase_id": { "type": "string", "description": "Also the id of the purchase's Alibi." }, "created_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "description": "`DENIED` when Keelson blocked the cart." }, "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "agent_id": { "type": "string", "description": "The ERC-8004 agent that made the purchase." }, "has_alibi": { "type": "boolean" }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "cart": { "type": [ "string", "null" ] } }, "required": [ "field", "cart" ] }, "description": "For a blocked cart, each mandate field whose check failed and what the cart had. The mandate's own bound stays with the buyer." }, "dispute": { "type": [ "object", "null" ], "properties": { "dispute_id": { "type": "string" }, "state": { "type": "string", "enum": [ "OPEN", "ATTRIBUTED", "RESOLVED" ] }, "liable": { "type": [ "string", "null" ], "enum": [ "operator", "keelson", "merchant", "user", null ] } }, "required": [ "dispute_id", "state", "liable" ] } }, "required": [ "purchase_id", "created_at", "state", "amount_minor", "currency", "agent_id", "has_alibi", "blocked", "dispute" ] }, "MerchantEvaluations": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string", "enum": [ "source", "evaluation_id", "at", "agent", "operator", "field", "color", "failed", "decision", "attack_class", "dispute_id", "liable" ] } }, "rows": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } } } }, "required": [ "columns", "rows" ], "description": "One row per mandate field per evaluation at this merchant: its countersigned purchases and the red-team campaigns' attacks. `failed` is 1 when the field's check failed." }, "AssistantTurn": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "claude-opus-5-5", "claude-haiku-5-5" ] }, "system": { "type": "string", "maxLength": 200000 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_use" ] }, "id": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 128 }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "id", "name", "input" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_use_id": { "type": "string", "maxLength": 128 }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false } } ] }, "is_error": { "type": "boolean" } }, "required": [ "type", "tool_use_id", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false } ] }, "minItems": 1 } ] } }, "required": [ "role", "content" ], "additionalProperties": false }, "minItems": 1, "maxItems": 400 }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }, "description": { "type": "string", "maxLength": 8000 }, "input_schema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "description", "input_schema" ], "additionalProperties": false }, "maxItems": 64 }, "tool_choice": { "type": "string", "enum": [ "auto", "none" ] } }, "required": [ "system", "messages" ], "description": "One turn of the console's agents: Messages API `system`, `messages` and client `tools`. The proxy sets the model limits, thinking and effort." }, "OperatorSelf": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "string" } }, "operators": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "chainId": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "agentId", "chainId", "name" ] } } }, "required": [ "wallets", "operators" ] }, "CoverageRow": { "type": "object", "properties": { "id": { "type": "string", "description": "The purchase id, also its Alibi's." }, "createdAt": { "type": "string", "format": "date-time" }, "merchantId": { "type": "string" }, "amount": { "type": "number", "description": "US dollars." }, "premiumBps": { "type": [ "integer", "null" ] }, "premium": { "type": "number", "description": "US dollars." }, "state": { "type": "string" }, "coverageTx": { "type": [ "string", "null" ], "format": "uri" }, "disputeId": { "type": [ "string", "null" ] }, "disputeState": { "type": [ "string", "null" ], "enum": [ "OPEN", "ATTRIBUTED", "RESOLVED", null ] }, "disputeReason": { "type": [ "string", "null" ] }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "liable": { "type": [ "string", "null" ], "enum": [ "operator", "keelson", "merchant", "user", null ] }, "rule": { "type": [ "string", "null" ] }, "verdictAmount": { "type": [ "number", "null" ], "description": "US dollars." }, "verdictAt": { "type": [ "string", "null" ], "format": "date-time" }, "outcome": { "type": [ "string", "null" ], "enum": [ "paid", "queued", "claimable", "failed", null ] }, "paidBy": { "type": [ "string", "null" ], "enum": [ "chain", "treasury", "violation-pool", null ] }, "settlementTx": { "type": [ "string", "null" ], "format": "uri" }, "settledAt": { "type": [ "string", "null" ], "format": "date-time" }, "amber": { "type": "string", "enum": [ "none", "attested", "contradicted" ], "description": "`attested`: you signed an amber commitment of the item into the coverage. `contradicted`: `AmberContradictionCourt` convicted it with a C2b proof." }, "amberCommitment": { "type": [ "string", "null" ] }, "amberField": { "type": [ "string", "null" ], "enum": [ "size", "color", "unit_price", "returns_free", null ], "description": "The field the court found false." }, "amberClaimed": { "type": [ "string", "null" ], "description": "What you attested of that field." }, "amberProvenAt": { "type": [ "string", "null" ], "format": "date-time" }, "amberWebFact": { "type": [ "string", "null" ], "description": "The digest of the `WebFact` the proof opened." }, "amberTx": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "createdAt", "merchantId", "amount", "premiumBps", "premium", "state", "coverageTx", "disputeId", "disputeState", "disputeReason", "disputedAt", "liable", "rule", "verdictAmount", "verdictAt", "outcome", "paidBy", "settlementTx", "settledAt", "amber", "amberCommitment", "amberField", "amberClaimed", "amberProvenAt", "amberWebFact", "amberTx" ] }, "CoverageRowsRequest": { "type": "object", "properties": { "startRow": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "endRow": { "type": "integer", "minimum": 1, "maximum": 10000100 }, "sortModel": { "type": "array", "items": { "type": "object", "properties": { "colId": { "type": "string", "enum": [ "id", "createdAt", "merchantId", "amount", "premiumBps", "premium", "state", "disputeState", "liable", "outcome", "paidBy", "amber" ] }, "sort": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "colId", "sort" ] }, "maxItems": 4, "default": [] }, "filterModel": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "createdAt": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "merchantId": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "amount": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "premiumBps": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "premium": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "state": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "disputeState": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "liable": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "outcome": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "paidBy": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] }, "amber": { "anyOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text", "number", "date" ] }, "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] } ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "filterType", "operator", "conditions" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "text" ] }, "type": { "type": "string", "enum": [ "contains", "notContains", "equals", "notEqual", "startsWith", "endsWith", "blank", "notBlank" ] }, "filter": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "number" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "filter": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 }, "filterTo": { "type": [ "number", "null" ], "minimum": -1000000000000, "maximum": 1000000000000 } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "date" ] }, "type": { "type": "string", "enum": [ "equals", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "inRange", "blank", "notBlank" ] }, "dateFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" }, "dateTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2})?$" } }, "required": [ "filterType", "type" ] }, { "type": "object", "properties": { "filterType": { "type": "string", "enum": [ "set" ] }, "values": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 64 }, "maxItems": 64 } }, "required": [ "filterType", "values" ] } ] } } } }, "required": [ "startRow", "endRow" ], "description": "AG Grid's `IServerSideGetRowsRequest`: the block, its sort and its filter model (text, number, date and set filters). Amounts are filtered in US dollars." }, "CoverageDay": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "coverages": { "type": "integer" }, "covered": { "type": "number", "description": "US dollars." }, "premiums": { "type": "number", "description": "US dollars." }, "incidents": { "type": "integer", "description": "Verdicts with the operator at fault on that day's coverages." } }, "required": [ "day", "coverages", "covered", "premiums", "incidents" ] }, "GridAnswer": { "type": "object", "properties": { "gridState": { "type": "object", "additionalProperties": {} }, "propertiesToIgnore": { "type": "array", "items": { "type": "string" } }, "explanation": { "type": "string" }, "model": { "type": "string" }, "costMicros": { "type": "integer", "description": "What the query cost, in USD micros." } }, "required": [ "gridState", "propertiesToIgnore", "explanation", "model", "costMicros" ] }, "GridQuery": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 500 }, "gridState": { "type": "object", "additionalProperties": {} }, "schema": { "type": "object", "additionalProperties": {}, "description": "`gridApi.getStructuredSchema()`, the JSON Schema of grid state." } }, "required": [ "prompt", "gridState", "schema" ] }, "Tracking": { "type": "object", "properties": { "carrier": { "type": "string", "pattern": "^[A-Z0-9_]{2,64}$", "description": "PayPal's carrier code.", "example": "USPS" }, "tracking_number": { "type": "string", "minLength": 1, "maxLength": 64 }, "delivered": { "type": "boolean", "default": false, "description": "The carrier confirmed delivery; it becomes the dispute's delivery proof." } }, "required": [ "carrier", "tracking_number" ] }, "JudgeSession": { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": [ "user_id" ] }, "JudgeTour": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "agent_id": { "type": [ "string", "null" ] }, "mandate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "mandate_hash": { "type": [ "string", "null" ] }, "budget": { "type": "object", "properties": { "currency": { "type": "string" }, "max_minor": { "type": "string" } }, "required": [ "currency", "max_minor" ] }, "created_at": { "type": "string", "format": "date-time" }, "card": { "allOf": [ { "$ref": "#/components/schemas/MandateCard" }, { "type": [ "object", "null" ] } ] }, "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/JudgeTourPurchase" } } }, "required": [ "id", "state", "mandate_hash", "budget", "created_at", "card", "purchases" ] }, "anonymous_purchase": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "alibi_fragment": { "type": [ "string", "null" ] } }, "required": [ "id", "alibi_fragment" ], "description": "The newest test purchase whose C1 and C3 proofs are composed into one anonymous proof, served at `GET /v1/anonymous-purchases/{id}`." }, "dispute_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] } }, "required": [ "merchant_id", "agent_id", "mandate", "anonymous_purchase", "dispute_id", "campaign_id" ] }, "JudgeTourPurchase": { "type": "object", "properties": { "id": { "type": "string", "description": "The purchase's ULID, which is also its Alibi id." }, "state": { "type": "string" }, "mode": { "type": [ "string", "null" ] }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] }, "merchant_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "log_index": { "type": [ "string", "null" ] }, "capture_id": { "type": [ "string", "null" ] }, "coverage_tx": { "type": [ "string", "null" ] }, "failure": { "type": [ "string", "null" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "color": { "type": "string" }, "pass": { "type": "boolean" } }, "required": [ "field", "color", "pass" ] }, "description": "Each mandate field the engine checked." }, "alibi_fragment": { "type": [ "string", "null" ], "description": "`..`: the fragment of the Alibi's verifier link, `https://verify.keelson.finance/a/#`." } }, "required": [ "id", "state", "mode", "amount", "merchant_id", "created_at", "log_index", "capture_id", "coverage_tx", "failure", "checks", "alibi_fragment" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "system" ], "summary": "Liveness probe", "responses": { "200": { "description": "The service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] } } } } } } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "system" ], "summary": "Dependency status", "responses": { "200": { "description": "Status of the service and its dependencies; always 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "dependencies": { "type": "object", "properties": { "db": { "type": "string", "enum": [ "up", "down" ] }, "kv": { "type": "string", "enum": [ "up", "down" ] }, "teeA": { "type": "string", "enum": [ "up", "down" ] }, "teeB": { "type": "string", "enum": [ "up", "down" ] }, "relayer": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down", "degraded" ] }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "status": { "type": "string", "enum": [ "up", "down", "degraded" ] }, "address": { "type": "string" }, "balanceWei": { "type": "string" }, "nextNonce": { "type": "string" }, "pending": { "type": "integer" }, "baseFeeWei": { "type": "string" } }, "required": [ "chainId", "status", "address", "pending" ] } } }, "required": [ "status", "chains" ] }, "log": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "size": { "type": "integer" }, "checkpointAgeMs": { "type": "integer" } }, "required": [ "origin", "size", "checkpointAgeMs" ] } } }, "required": [ "status", "origins" ] }, "paypal": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "status", "environment" ] }, "webhooks": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "lastWebhookAgeMs": { "type": "integer" }, "lastPollAgeMs": { "type": "integer" } }, "required": [ "status" ] }, "chainEvents": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "finalizedBlock": { "type": "string" }, "reconciledAgeMs": { "type": "integer" } }, "required": [ "status" ] }, "anchor": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "environment": { "type": "string", "enum": [ "arbitrum-sepolia" ] }, "size": { "type": "string" }, "anchoredAgeMs": { "type": "integer" } }, "required": [ "status", "environment" ] } }, "required": [ "db", "kv" ] }, "rpc": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "method": { "type": "string" }, "calls": { "type": "integer" } }, "required": [ "provider", "method", "calls" ] } } }, "required": [ "calls" ] }, "version": { "type": "string" } }, "required": [ "status", "dependencies", "rpc", "version" ] } } } } } } }, "/v1/events": { "get": { "operationId": "streamEvents", "tags": [ "events" ], "summary": "Stream events", "description": "Server-sent events for one channel. Send `Last-Event-ID` to replay the events after that id before going live.", "security": [ { "session": [] }, { "oauth2": [] } ], "parameters": [ { "schema": { "type": "string", "description": "`public:`, or the caller's own namespace `` with an optional `:`." }, "required": true, "description": "`public:`, or the caller's own namespace `` with an optional `:`.", "name": "channel", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "last-event-id", "in": "header" } ], "responses": { "200": { "description": "An event stream; each event carries the row id, the channel and a JSON payload", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid channel or Last-Event-ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The channel belongs to another principal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many concurrent streams for this principal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates": { "post": { "operationId": "createMandate", "tags": [ "mandates" ], "summary": "Store a passkey-signed mandate", "description": "Verifies the passkey assertion over `M = SHA-256(\"keelson/mandate-challenge/v1\" || 0x00 || H_sd || C_m)` and stores the mandate as `SIGNED`, or `ACTIVE` when it allows several merchants.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMandate" } } } }, "responses": { "201": { "description": "The mandate was stored", "headers": { "location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedMandate" } } } }, "401": { "description": "Not signed in, or the signature is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The passkey is not the signer's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is already stored", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The mandate is invalid (`invalid-mandate`), or it binds an agent key, a bond, an engine build, a policy set or terms other than the ones `POST /v1/mandates/compile` fills: the named operator's registered `cnf` key, its bond vault with the 50 PYUSD minimum, the engine version and TEE measurements of the build the legs run (or of another build admitted during a rotation), the current policy set hash and the current terms (`mandate-binding-mismatch`; `fields` names `agent.cnf`, `agent.bond`, `policy.engine`, `policy.version`, `policy.measurements`, `policy.policy_set_hash` or `consent`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many approvals by user code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The TEE could not issue the mandate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listMandates", "tags": [ "mandates" ], "summary": "List your mandates", "description": "The signed-in user's latest 50 signed mandates, newest first.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The mandates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandates" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}": { "get": { "operationId": "getMandate", "tags": [ "mandates" ], "summary": "Get a mandate", "description": "Renders the card of the signed mandate. The user answered for every field when signing, so fields that were ambiguous at compile time show with the colors the engine enforces, not gray.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The mandate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/paypal/client": { "get": { "operationId": "getPayPalClient", "tags": [ "paypal" ], "summary": "Get the PayPal client ID", "description": "The client ID and environment the JavaScript SDK loads with. The client ID is public by design.", "responses": { "200": { "description": "The PayPal client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalClient" } } } }, "503": { "description": "PayPal is not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/hold": { "post": { "operationId": "holdMandate", "tags": [ "mandates" ], "summary": "Hold a mandate's budget", "description": "Creates the PayPal `AUTHORIZE` order for the budget of a signed mandate, bound to the signed mandate hash by its `custom_id`, and moves the mandate to `HOLD_PENDING`. With the user's saved PayPal, PayPal authorizes the order as it creates it (`approved`); otherwise the buyer approves it in PayPal. While the mandate waits for approval the same order is returned; an order PayPal no longer offers is replaced.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "The order the buyer approves", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldOrder" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not signed, or it holds each purchase separately", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Keelson cannot capture for the mandate's merchant, PayPal refused, or the hold would pass the hosted operator's total cap (`hosted-cap`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/hold/authorize": { "post": { "operationId": "authorizeMandateHold", "tags": [ "mandates" ], "summary": "Authorize an approved hold", "description": "Authorizes the order stored for the mandate, checks the authorization against the signed mandate (amount, currency, `custom_id`, payee) and moves the mandate to `ACTIVE`. An authorization that does not match is voided.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeHold" } } } }, "responses": { "200": { "description": "The mandate is active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedHold" } } } }, "202": { "description": "PayPal holds the authorization as pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingHold" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not waiting for its hold, or the order is not its order", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The authorization does not match the mandate, or PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/paypal/wallet/setup-token": { "post": { "tags": [ "paypal" ], "summary": "Start saving PayPal", "description": "Creates the PayPal Vault setup token the user approves in PayPal, for one merchant-initiated token billed on the terms of the mandates they sign.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "201": { "description": "The setup token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalSetupToken" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/paypal/wallet": { "post": { "tags": [ "paypal" ], "summary": "Save PayPal", "description": "Exchanges the setup token the user approved for a payment token and saves it as the user's PayPal for holds, in place of any saved before.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalSetupToken" } } } }, "responses": { "201": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalWallet" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such setup token of this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "paypal" ], "summary": "The saved PayPal", "security": [ { "session": [] } ], "responses": { "200": { "description": "The saved PayPal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalWallet" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No saved PayPal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "paypal" ], "summary": "Remove the saved PayPal", "description": "Deletes the payment token at PayPal and forgets it. Holds already authorized stay until they are captured, voided or expire; new holds need PayPal's approval again.", "security": [ { "session": [] } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No saved PayPal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/holds": { "post": { "operationId": "holdCart", "tags": [ "mandates" ], "summary": "Hold one cart of a multi-merchant mandate", "description": "For a mandate that allows several merchants, creates the PayPal `AUTHORIZE` order for exactly one cart, keyed by the request id it will be countersigned under. The user approves it like a mandate hold.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePurchaseHold" } } } }, "responses": { "201": { "description": "The order the buyer approves", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseHoldOrder" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not the mandate's agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate holds its whole budget, is not active, or the request id is already used", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The cart is outside the mandate, its open cart holds with this one exceed the remaining budget, Keelson cannot capture for it, PayPal refused, or the hold would pass the hosted operator's total cap (`hosted-cap`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/holds/{requestId}/authorize": { "post": { "operationId": "authorizeCartHold", "tags": [ "mandates" ], "summary": "Authorize an approved cart hold", "description": "Authorizes the order stored for the request and checks the authorization against it (amount, currency, `custom_id`, payee). An authorization that does not match is voided.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "requestId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizePurchaseHold" } } } }, "responses": { "200": { "description": "The cart is held", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedPurchaseHold" } } } }, "202": { "description": "PayPal holds the authorization as pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedPurchaseHold" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such hold for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not active, the hold is not pending, or the order is not its order", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The authorization does not match the hold, or PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/revoke": { "post": { "operationId": "revokeMandate", "tags": [ "mandates" ], "summary": "Revoke a mandate", "description": "Stops new countersigns at once, voids the PayPal hold and moves the mandate to `REVOKED`. While a countersigned purchase may still be captured, the void waits for it and the revocation completes in the background.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "The mandate is revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedMandate" } } } }, "202": { "description": "The mandate is being revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokingMandate" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate has already ended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "PayPal refused the void", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal is unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections": { "post": { "operationId": "requestMandate", "tags": [ "connections" ], "summary": "Ask the user for a mandate", "description": "The agent's operator asks its user for a mandate with these limits, as an RFC 8628 device authorization: the user opens `verification_uri_complete`, compares `user_code` and approves on Keelson's page with a passkey, lowering any limit. Only a client that linked an operator may ask, and the mandate names that operator. The code expires in 15 minutes and is single use.\n\nAn app acting for a user with a token they granted it (`mandates:request`) asks that user only: the request is theirs from the start, so it carries no number to match. The mandate names the app's own operator, or Keelson's hosted operator when the app has none. Through the hosted operator, every app is capped (`hosted-cap`): one user's open mandates and purchases of the last 180 days with apps whose redirect URIs are not a known host's may not pass `HOSTED_CAP_PER_USER_MINOR`, and with all such apps `HOSTED_CAP_KNOWN_PER_USER_MINOR`; every user's funded exposure may not pass `HOSTED_CAP_TOTAL_MINOR`.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "mandates:request" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionRequest" } } } }, "responses": { "201": { "description": "Show the code and the link to the user, then poll", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The client linked no operator, and no hosted operator serves it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The client linked several operators", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is invalid, or over the hosted operator's cap (`hosted-cap`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/token": { "post": { "operationId": "pollConnection", "tags": [ "connections" ], "summary": "Poll for the user's answer", "description": "RFC 8628 §3.4 polling with `grant_type=urn:ietf:params:oauth:grant-type:device_code`. Until the user decides: `authorization_pending`, or `slow_down` (and 5 more seconds to wait) when polled faster than `interval`. Then `access_denied`, `expired_token`, or the approved mandate's id, once: the device code is spent by the answer that carries it.", "security": [ { "oauth2": [ "countersign:write" ] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" }, "device_code": { "type": "string", "maxLength": 256 } }, "required": [ "grant_type", "device_code" ] } } } }, "responses": { "200": { "description": "Approved: the mandate the user signed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionApproved" } } } }, "400": { "description": "Not approved, or not yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTokenError" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{code}": { "get": { "operationId": "getConnectionByCode", "tags": [ "connections" ], "summary": "Read a request by its user code", "description": "What the agent asks for, for the approval page. Limited to 20 reads a minute per user, so codes cannot be guessed.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 8, "maxLength": 16 }, "required": true, "name": "code", "in": "path" } ], "responses": { "200": { "description": "The request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such request for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many reads", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{code}/deny": { "post": { "operationId": "denyConnection", "tags": [ "connections" ], "summary": "Deny a request", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 8, "maxLength": 16 }, "required": true, "name": "code", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Denied; the agent's next poll says `access_denied`", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "DENIED" ] } }, "required": [ "state" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No open request with this code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{code}/match": { "post": { "operationId": "matchConnection", "tags": [ "connections" ], "summary": "Pick the agent's number", "description": "The user picks the number the agent shows beside its link out of the three the request offers. The right one opens the request; a wrong one denies it, since the link may not be the user's agent's.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 8, "maxLength": 16 }, "required": true, "name": "code", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 10, "maximum": 99 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Matched", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "boolean", "enum": [ true ] } }, "required": [ "matched" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No open request with this code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not the agent's number (`number-mismatch`); the request is denied", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/requests/{id}": { "get": { "operationId": "getConnectionRequest", "tags": [ "connections" ], "summary": "Read your request's state", "description": "The state of a request this client made, as often as needed: reading it changes nothing and does not spend the device code. Wait `interval` seconds between reads. An app acting for a user (`mandates:request`) reads only that user's requests.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "mandates:request" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionRequestState" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such request of this client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{code}/draft": { "post": { "operationId": "draftConnectionMandate", "tags": [ "connections" ], "summary": "Draft the mandate that approves a request", "description": "The unsigned mandate for the limits the user chose, which may only be lower than or equal to what the agent asked. It names the asking agent's operator. Sign it and store it with `POST /v1/mandates`, passing `connection`, to approve.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 8, "maxLength": 16 }, "required": true, "name": "code", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" }, { "schema": { "type": "string" }, "required": false, "name": "keelson-device", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDraft" } } } }, "responses": { "200": { "description": "The draft mandate and its card", "content": { "application/json": { "schema": { "type": "object", "properties": { "mandateDraft": { "type": "object", "additionalProperties": {} }, "card": { "$ref": "#/components/schemas/MandateCard" }, "ambiguous": { "type": "array", "items": { "type": "string" } }, "check": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped" ] }, "discrepancies": { "type": "null" } }, "required": [ "status", "discrepancies" ] } }, "required": [ "mandateDraft", "card", "ambiguous", "check" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The passkey is not the user's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No open request with this code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The user has no passkey", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A limit is above what the agent asked (`limits-raised`; `fields` names it)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The operator's agent key or bond is not set", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/changes": { "post": { "operationId": "requestMandateChange", "tags": [ "mandates" ], "summary": "Ask the user to change a mandate", "description": "The agent asks its user for different limits, with a one-line note the user reads verbatim. The user may lower what is asked and approves with a passkey; the new mandate then replaces this one, whose hold is released. Nothing changes until the user signs. Poll `GET /v1/connections/requests/{id}` for the answer. An app acting for a user (`mandates:request`) asks only about a mandate that user approved for it.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "mandates:request" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateChangeRequest" } } } }, "responses": { "201": { "description": "The user was asked; show the link and poll", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } }, "required": [ "request_id", "user_code", "verification_uri_complete", "expires_in", "interval" ] } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate of an operator this client linked, or that the user approved for this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate has ended, or a change of it is already waiting for the user (`change-pending`, with its `requestId`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The limits are invalid, or over the hosted operator's cap (`hosted-cap`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/{id}/check": { "post": { "operationId": "checkCart", "tags": [ "mandates" ], "summary": "Check a cart against a mandate", "description": "A dry run: what a countersign of this cart would find, field by field, from the same policy set the TEE legs run, with nothing signed, reserved or logged. The countersign stays the only decision. An app acting for a user (`purchases:write`) checks only under a mandate that user approved for it.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "purchases:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/Cart" } }, "required": [ "cart" ] } } } }, "responses": { "200": { "description": "The check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartCheck" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate of an operator this client linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/origins": { "put": { "operationId": "setEmbedOrigins", "tags": [ "embed" ], "summary": "Set the origins that may frame approvals", "description": "Replaces the https origins this client's agent platform may embed Keelson's approval in. Each becomes the page's `frame-ancestors` for that client's requests, and the only origin the frame talks to with `postMessage`.", "security": [ { "oauth2": [ "countersign:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedOrigins" } } } }, "responses": { "200": { "description": "The origins now allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedOrigins" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "An origin is not a bare https origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/embed": { "post": { "operationId": "embedConnection", "tags": [ "embed" ], "summary": "Embed the approval of a request", "description": "For a pending request this client made, a URL to frame in the agent platform's page at `origin`, one of the client's embed origins. The URL's fragment carries a single-use token the frame redeems within five minutes; mint another to frame it again. The user approves in a Keelson window the frame opens, with a passkey; poll `POST /v1/connections/token` as usual for the answer.", "security": [ { "oauth2": [ "countersign:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "maxLength": 256 }, "origin": { "type": "string", "maxLength": 255 } }, "required": [ "device_code", "origin" ] } } } }, "responses": { "201": { "description": "Frame `url`; it opens to the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedUrl" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The origin is not one of this client's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No pending request with this device code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/sessions": { "post": { "operationId": "openEmbedSession", "tags": [ "embed" ], "summary": "Open the embedded approval", "description": "The frame spends its token, once, for a session it keeps in memory and sends in `Keelson-Embed`. No cookie is read or set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 64 } }, "required": [ "token" ] } } } }, "responses": { "201": { "description": "The session and the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSession" } } } }, "401": { "description": "The token is unknown, spent or expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/request": { "get": { "operationId": "getEmbedRequest", "tags": [ "embed" ], "summary": "Read the embedded request", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "responses": { "200": { "description": "The request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedRequest" } } } }, "401": { "description": "No live embed session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/deny": { "post": { "operationId": "denyEmbedRequest", "tags": [ "embed" ], "summary": "Decline the embedded request", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "responses": { "200": { "description": "Declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedRequest" } } } }, "401": { "description": "No live embed session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The request is no longer pending", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/sign-in/options": { "post": { "operationId": "getEmbedSignInOptions", "tags": [ "embed" ], "summary": "Start a passkey sign-in in the embedded approval", "description": "WebAuthn request options for any of the user's passkeys, with a challenge for this embed session only. The frame passes them to `navigator.credentials.get`.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "responses": { "200": { "description": "The options", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "No live embed session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/sign-in": { "post": { "operationId": "signInEmbed", "tags": [ "embed" ], "summary": "Sign in with a passkey in the embedded approval", "description": "Verifies the assertion against the session's challenge. It must come from the approval in a frame whose top-level origin is the embed's platform (`crossOrigin` true, `topOrigin` that origin). The session then signs for the passkey's user.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnResponse" } } } }, "responses": { "200": { "description": "Who the frame signs for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSigner" } } } }, "401": { "description": "No live embed session, or the passkey did not verify", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/links": { "post": { "operationId": "createEmbedLink", "tags": [ "embed" ], "summary": "Link the embedded approval to a Keelson window", "description": "A single-use nonce for the Keelson window the frame opens for a user without a passkey here: once they sign in there and confirm, this session signs for them.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "responses": { "201": { "description": "The nonce", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedLink" } } } }, "401": { "description": "No live embed session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/links/inspect": { "post": { "operationId": "inspectEmbedLink", "tags": [ "embed" ], "summary": "Read a link in the Keelson window", "description": "The agent platform and the request an unspent link was opened for, so the window can show the user which page they are about to link before they confirm.", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string", "maxLength": 64 } }, "required": [ "nonce" ] } } } }, "responses": { "200": { "description": "The link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedLink" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "The link is unknown, spent or expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/links/confirm": { "post": { "operationId": "confirmEmbedLink", "tags": [ "embed" ], "summary": "Confirm a link from the Keelson window", "description": "The signed-in user confirms the embedded approval that opened this window, named by its `ref`. The answer is a single-use grant the window hands only to that frame, its opener on Keelson's origin; the frame claims it with `POST /v1/embed/links/claim`. The frame may create a passkey only for a user who has none.", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string", "maxLength": 64 }, "ref": { "type": "string", "maxLength": 26 } }, "required": [ "nonce", "ref" ] } } } }, "responses": { "200": { "description": "The grant for the frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedLinked" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "The link is unknown, spent, expired or for another request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/links/claim": { "post": { "operationId": "claimEmbedLink", "tags": [ "embed" ], "summary": "Claim a link's grant in the embedded approval", "description": "The frame redeems the grant its Keelson window handed it. It works once, and only for the session that opened the link; the session then signs for that user.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "type": "string", "maxLength": 64 } }, "required": [ "grant" ] } } } }, "responses": { "200": { "description": "Who the frame signs for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSigner" } } } }, "401": { "description": "No live embed session, or the grant is not this session's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/passkeys/options": { "post": { "operationId": "getEmbedPasskeyOptions", "tags": [ "embed" ], "summary": "Start creating a passkey in the embedded approval", "description": "WebAuthn creation options for the session's user, who linked a Keelson window. With `platform`, the passkey is created on this device's platform authenticator with the SPC `payment` extension.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "boolean" } }, "required": [ "platform" ] } } } }, "responses": { "200": { "description": "The options", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "No live embed session, or no user linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/passkeys": { "post": { "operationId": "createEmbedPasskey", "tags": [ "embed" ], "summary": "Create a passkey in the embedded approval", "description": "Verifies the new credential against the session's challenge, made in the approval framed by the embed's platform, and stores it as the user's passkey (ES256 only).", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnResponse" } } } }, "responses": { "201": { "description": "Who the frame signs for, with the new passkey", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSigner" } } } }, "401": { "description": "No live embed session, or no user linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The credential did not verify", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/draft": { "post": { "operationId": "draftEmbedMandate", "tags": [ "embed" ], "summary": "Draft the mandate in the embedded approval", "description": "As `POST /v1/connections/{code}/draft`, for the embedded request and the session's user. The mandate carries `embed.top_origin`, the platform's origin, so only an assertion made in this frame signs it.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" }, { "schema": { "type": "string" }, "required": false, "name": "keelson-device", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDraft" } } } }, "responses": { "200": { "description": "The draft mandate and its card", "content": { "application/json": { "schema": { "type": "object", "properties": { "mandateDraft": { "type": "object", "additionalProperties": {} }, "card": { "$ref": "#/components/schemas/MandateCard" }, "ambiguous": { "type": "array", "items": { "type": "string" } }, "check": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped" ] }, "discrepancies": { "type": "null" } }, "required": [ "status", "discrepancies" ] } }, "required": [ "mandateDraft", "card", "ambiguous", "check" ] } } } }, "401": { "description": "No live embed session, or no user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The passkey is not the user's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "The request is no longer open", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The user has no passkey", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A limit is above what the agent asked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The operator's agent key or bond is not set", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/embed/mandates": { "post": { "operationId": "createEmbedMandate", "tags": [ "embed" ], "summary": "Approve the embedded request with a signed mandate", "description": "As `POST /v1/mandates` with `connection`, for the embedded request and the session's user. The mandate's `embed.top_origin` must be the platform's origin, still registered, and the assertion must be made in this frame under it.", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "keelson-embed", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payloadSd": { "type": "object", "additionalProperties": {}, "description": "The SD-JWT payload with its `_sd` digests, as signed." }, "disclosures": { "type": "array", "items": { "type": "string" }, "maxItems": 1024, "description": "Every disclosure of the payload; each digest must resolve." }, "commitment": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "`C_m`; must equal the payload's `zk.commitment`." }, "salt": { "type": "string", "pattern": "^0x[0-9a-f]{32}$", "description": "The salt that opens `C_m`; the TEE needs it to issue the mandate." }, "assertion": { "$ref": "#/components/schemas/PasskeyAssertion" }, "askAboveMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "payloadSd", "disclosures", "commitment", "assertion" ] } } } }, "responses": { "201": { "description": "The mandate; the request is approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedMandate" } } } }, "401": { "description": "No live embed session, no user, or a bad signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The passkey is not the user's, or the origin is no longer registered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "The request is no longer open", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The request was already answered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The mandate is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many approvals", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Leg A cannot issue the mandate now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/agents": { "get": { "operationId": "listAgents", "tags": [ "agents" ], "summary": "List your agents", "description": "Each agent that holds or held a mandate of yours, or that you connected: its live mandate with what is left, and when it last acted.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The agents, most recently active first", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } }, "required": [ "agents" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/approvals": { "get": { "operationId": "listApprovals", "tags": [ "agents" ], "summary": "Carts paused for your approval", "description": "Carts your agents tried that their mandate does not allow, each waiting for you to approve it once or decline it. New ones arrive as `approval.requested` events on the `agents` channel.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The open requests, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/PendingApproval" } } }, "required": [ "approvals" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/agents/stop": { "post": { "operationId": "stopAgents", "tags": [ "agents" ], "summary": "Stop all agents", "description": "The kill switch. Keelson refuses every countersign of a mandate of yours stored before now, revokes every live mandate and voids its PayPal holds, denies every open request, revokes every agent's OAuth grant, and logs the stop as a `keelson.finance/stop/v1` leaf in the Alibi log. Purchases already countersigned may still be captured.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStop" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/agents/stops": { "get": { "operationId": "listAgentStops", "tags": [ "agents" ], "summary": "Your stops", "description": "Each time you stopped all agents, newest first, with its log index.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The stops", "content": { "application/json": { "schema": { "type": "object", "properties": { "stops": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStop" } } }, "required": [ "stops" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/agents/{agentId}/disconnect": { "post": { "operationId": "disconnectAgent", "tags": [ "agents" ], "summary": "Disconnect an agent", "description": "Revokes every live mandate of yours that names the agent and ends its connections. Keelson refuses its countersigns from now on; purchases already countersigned may still be captured.\n\nWith `client`, only that app, of the apps acting through the agent: the mandates you approved for it, its requests, its OAuth grant and refresh tokens, and the access tokens it holds for you. Apps acting through Keelson's hosted operator are disconnected this way; without `client`, the hosted operator ends only your mandates of it that no app holds (its `Unknown app` row).", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": false, "name": "client", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsRevoked" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No agent of yours with this id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/activity": { "get": { "operationId": "listActivity", "tags": [ "agents" ], "summary": "Read your activity", "description": "What your agents and Keelson did, newest first, one plain line each: requests, purchases, blocks and stops. Purchases link to their Alibi and log entry.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,77})$", "description": "Only this agent's rows, and stops of every agent." }, "required": false, "description": "Only this agent's rows, and stops of every agent.", "name": "agent", "in": "query" } ], "responses": { "200": { "description": "The feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRow" } } }, "required": [ "rows" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/push/key": { "get": { "operationId": "getPushKey", "tags": [ "alerts" ], "summary": "Read the push key", "description": "The VAPID public key (RFC 8292) to pass as `applicationServerKey` to `PushManager.subscribe()`.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The key, base64url", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string" } }, "required": [ "publicKey" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Alerts are not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/push/subscriptions": { "post": { "operationId": "createPushSubscription", "tags": [ "alerts" ], "summary": "Get alerts on this browser", "description": "Stores the browser's push subscription: agent requests, blocked carts and stops are pushed to it.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscription" } } } }, "responses": { "201": { "description": "Subscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deletePushSubscription", "tags": [ "alerts" ], "summary": "Stop alerts on this browser", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 2048 } }, "required": [ "endpoint" ] } } } }, "responses": { "204": { "description": "Removed" }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/push/test": { "post": { "operationId": "sendTestPush", "tags": [ "alerts" ], "summary": "Send a test notification", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "How many browsers' push services accepted it", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer" } }, "required": [ "sent" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Alerts are not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alerts/email": { "get": { "operationId": "getAlertEmail", "tags": [ "alerts" ], "summary": "Read your alert address", "security": [ { "session": [] } ], "responses": { "200": { "description": "The address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertEmail" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "setAlertEmail", "tags": [ "alerts" ], "summary": "Set your alert address", "description": "Stores the address unconfirmed and sends it a confirmation link, signed, single use and valid for 24 hours. Alerts are emailed only once it is confirmed. Never the sign-in address unless entered here.", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 254, "format": "email" } }, "required": [ "address" ] } } } }, "responses": { "202": { "description": "The confirmation link was sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertEmail" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "A link was sent less than a minute ago", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Alerts are not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAlertEmail", "tags": [ "alerts" ], "summary": "Stop email alerts", "security": [ { "session": [] } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alerts/email/confirm": { "post": { "operationId": "confirmAlertEmail", "tags": [ "alerts" ], "summary": "Confirm an alert address", "description": "Opened from the confirmation link; needs no session. A link works once.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 1024 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" } }, "required": [ "address" ] } } } }, "404": { "description": "The link is invalid, used or expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Alerts are not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alerts/unsubscribe": { "post": { "operationId": "unsubscribeAlerts", "tags": [ "alerts" ], "summary": "Unsubscribe in one click", "description": "The `List-Unsubscribe` URI of every alert email (RFC 8058): the mail client posts `List-Unsubscribe=One-Click` to it, with no session or other context. The token in the query names the address.", "parameters": [ { "schema": { "type": "string", "maxLength": 1024 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "No more email goes to the address", "content": { "application/json": { "schema": { "type": "object", "properties": { "unsubscribed": { "type": "boolean", "enum": [ true ] } }, "required": [ "unsubscribed" ] } } } }, "404": { "description": "The link is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Alerts are not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alerts/emails": { "get": { "operationId": "listAlertEmails", "tags": [ "alerts" ], "summary": "List the emails sent to you", "description": "Every alert email composed for you, newest first, with what it reported.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/SentEmail" } } }, "required": [ "emails" ] } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/mandates/compile": { "post": { "operationId": "compileMandate", "tags": [ "mandates" ], "summary": "Compile a mandate from a shopping request", "description": "Two models compile the request independently; fields they disagree on or the request leaves unstated come back ambiguous, and a third model checks the rendered card against the request. Limited to 10 requests a minute per user.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" }, { "schema": { "type": "string", "maxLength": 128, "description": "The app's opaque device id, recorded as `risk_data.device_fp`. Required." }, "required": false, "description": "The app's opaque device id, recorded as `risk_data.device_fp`. Required.", "name": "keelson-device", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileMandate" } } } }, "responses": { "200": { "description": "The draft mandate and its card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompiledMandate" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The passkey is not the user's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The user has no passkey to sign with", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The prompt is too long (`prompt-too-long`), the device id is missing (`device-required`), the compilations conflict (`compile-conflict`), the request leaves out a value a mandate needs (`compile-needs-input`) or cannot become a mandate (`compile-unresolved`); `fields` names what to ask the user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many compilations", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The models failed to compile the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Inputs a mandate needs are not available yet (`compile-unavailable`; `missing` names them), or the rate limit store is unreachable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/countersign": { "post": { "operationId": "countersign", "tags": [ "tee" ], "summary": "Countersign a cart", "description": "Sends the cart to the TEE legs in order and returns the countersignatures only when both agree. A DENY is countersigned too. An app acting for a user (`purchases:write`) countersigns only under a mandate that user approved for it; under a mandate of Keelson's hosted operator it sends `mandateId` and Keelson closes the mandate with that operator's key over the request id and this cart, and nothing else. A cart is bought once per mandate: while a purchase of the same cart is in flight, or for ten minutes after it was captured, another request for it is answered `409 purchase-exists` with that purchase's id, whatever its request id, evidence or `Idempotency-Key`. Retrying after a lost answer is therefore safe; to buy the same cart again on purpose, name that purchase in `repeatOf`.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "purchases:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountersignRequest" } } } }, "responses": { "200": { "description": "The decision and its countersignatures", "headers": { "Keelson-Countersign-Mode": { "schema": { "type": "string", "enum": [ "2of2", "degraded" ], "description": "`degraded` when only one TEE signed; the same as `mode` in the body." }, "required": true, "description": "`degraded` when only one TEE signed; the same as `mode` in the body." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Countersigned" } } } }, "202": { "description": "Countersigned, and a step of the purchase is still pending; `Location` is the purchase, which finishes on its own", "headers": { "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Countersigned" } } } }, "401": { "description": "A leg refused the agent's authority", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such mandate of an operator this client linked, or that the user approved for this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not active, the evidence root is not stored for it or already binds another purchase, the request was already used, or the same cart is already being bought (`purchase-exists`, with its `purchaseId`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "A leg refused the request as too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is invalid, the purchase unit's amount does not reconcile with the cart (`invalid-amount`), the authorization is not this purchase's hold, the cart is not the one held for this request, the evidence holds another cart or another checkout amount or reference rates Keelson did not issue, its Channel3 observation is not usable, its WebFact is not this purchase's, or a live store is not the website the mandate allows", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many countersigns for this mandate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The legs disagree, or a signer is not registered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A leg needed to sign, or PayPal, is unavailable, or the hosted operator's key is not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/live-purchases": { "get": { "operationId": "listLivePurchases", "tags": [ "purchases" ], "summary": "Live purchases", "description": "Purchases the shopping agent made with real money at real stores' own checkouts, and the carts Keelson denied there before the payment for Keelson's own test users, newest first. Each has a public Alibi; a paid one names the PayPal transaction it paid. Keelson countersigned and logged them; it covers none of them.", "responses": { "200": { "description": "The live purchases", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/LivePurchase" } } }, "required": [ "purchases" ] } } } } } } }, "/v1/purchases/{id}/paypal-transaction": { "put": { "operationId": "recordPayPalTransaction", "tags": [ "purchases" ], "summary": "Record a live purchase's PayPal transaction", "description": "For a purchase countersigned with `live`, once its Alibi is issued: the PayPal transaction id of the buyer's payment at the store, as PayPal reported it on its confirmation. Recorded once; the Alibi carries it from then on, marked as not signed. Only the client that asked for the countersign records it.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalTransaction" } } } }, "responses": { "200": { "description": "The purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "404": { "description": "No such purchase of this client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The purchase is not live, its Alibi is not issued yet, or another transaction id is recorded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The order's payee is not one the mandate allows, or the conversion is not the countersigned amount at PayPal's rate, does not use the reference rate the evidence binds, or is over the mandate's spread. The transaction id is recorded without them.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/purchases/{id}": { "get": { "operationId": "getPurchase", "tags": [ "purchases" ], "summary": "A purchase", "description": "The purchase's state: its log index, its coverage and its capture once each is recorded. Readable by the mandate's owner and by the client that asked for the countersign; an app acting for a user, only for that user.", "security": [ { "session": [] }, { "oauth2": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "404": { "description": "No such purchase, or not the caller's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/purchases/{id}/card": { "get": { "operationId": "getPurchaseCard", "tags": [ "purchases" ], "summary": "The single-use card of a card purchase", "description": "For the agent's browser: a one-minute link to the card issuer's hosted page showing the card's number, expiry and code. Open it in the browser session that pays; never put its contents in a model's context or a log. Only the client that asked for the countersign reads it, and only while the card is open.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The card's hosted page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCard" } } } }, "404": { "description": "No such card purchase of this client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The card is not open", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/evidence": { "post": { "operationId": "storeEvidence", "tags": [ "evidence" ], "summary": "Store sealed evidence", "description": "Stores what the agent saw at decision time for an active mandate of an operator this client linked or, for an app acting for a user, one that user approved for the app. The manifest is rebuilt from the items and must match, every item has its own salt, no public item may still hold an email address or phone number, and every `.original` must open with the evidence identity. A countersign may only bind a stored root, once.", "security": [ { "oauth2": [ "evidence:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceUpload" } } } }, "responses": { "201": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidenceRoot": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "evidenceRoot" ] } } } }, "404": { "description": "No such mandate of an operator this client linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not active, holds the most bundles it may, or the root is stored for another mandate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The bundle is larger than 16 MiB", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The items do not build the manifest, a public item holds PII, or an original does not open", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many uploads for this mandate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/evidence/{root}": { "get": { "operationId": "getEvidenceManifest", "tags": [ "evidence" ], "summary": "Read an evidence manifest", "description": "The public manifest of a stored bundle: salted leaves only.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "required": true, "name": "root", "in": "path" } ], "responses": { "200": { "description": "The manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceManifest" } } } }, "404": { "description": "No such bundle", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/evidence/{root}/items/{index}": { "get": { "operationId": "discloseEvidenceItem", "tags": [ "evidence" ], "summary": "Disclose one evidence item", "description": "One item with its content hash, salt and inclusion proof, for an arbiter. Every disclosure is recorded with its `reason`. An `.original` item stays age ciphertext unless `decrypt=1` is sent with the `evidence:decrypt` scope.", "security": [ { "oauth2": [ "evidence:disclose" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "required": true, "name": "root", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 25 }, "required": true, "name": "index", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Why the item is opened, such as the dispute it serves." }, "required": true, "description": "Why the item is opened, such as the dispute it serves.", "name": "reason", "in": "query" }, { "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "name": "decrypt", "in": "query" } ], "responses": { "200": { "description": "The item and its disclosure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosedEvidence" } } } }, "403": { "description": "Decrypting needs the `evidence:decrypt` scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such bundle or item", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The item is not an `.original`, or it does not open with the evidence identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The evidence identity is not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/observations/channel3": { "post": { "operationId": "observeChannel3", "tags": [ "evidence" ], "summary": "Observe a product through Channel3", "description": "Asks Channel3 about the product page once (live fetch if its data is older than an hour, eight seconds at most), compares variant, price, availability and brand with what the agent saw, stores the observation and queues RFC 3161 tokens over its hash. Channel3 is third-party testimony: it is shown in the countersigned trace and never changes a decision.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel3ObservationRequest" } } } }, "responses": { "201": { "description": "The observation and its sealed evidence item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel3Observation" } } } }, "404": { "description": "No such mandate of an operator this client linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The mandate is not active", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many observations for this mandate, or today for this client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Channel3 is not configured, or the rate limit store is unreachable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/observations/channel3/{id}": { "get": { "operationId": "getChannel3Observation", "tags": [ "evidence" ], "summary": "Read a Channel3 observation", "description": "The stored observation document and its hash; `GET /v1/timestamps/{content_hash}` serves its RFC 3161 tokens. Only the client that asked for it may read it.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 26, "maxLength": 26 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The observation", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": {}, "description": "The `keelson.channel3.observation/1` document; its JCS bytes hash to `content_hash`." }, "content_hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "document", "content_hash" ] } } } }, "404": { "description": "No such observation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/fx/reference/{base}": { "get": { "operationId": "getFxReference", "tags": [ "purchases" ], "summary": "Reference exchange rates", "description": "Mid-market rates from the merchant's currency to every other one, from ExchangeRate-API (Rates By Exchange Rate API, https://www.exchangerate-api.com), at most 48 hours old. The agent binds them into a purchase's evidence as an `api.fx_reference` item, `commitReference` of this answer, which a countersign accepts only for references the API issued in the last 6 hours. The pay-click gate checks the rate PayPal converts the charge at against them, within the mandate's `fx.max_spread_bps`.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "AUD", "BRL", "CAD", "CNY", "CZK", "DKK", "EUR", "HKD", "HUF", "ILS", "JPY", "MYR", "MXN", "TWD", "NZD", "NOK", "PHP", "PLN", "GBP", "SGD", "SEK", "CHF", "THB", "USD" ] }, "required": true, "name": "base", "in": "path" } ], "responses": { "200": { "description": "The rates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxReference" } } } }, "503": { "description": "No current reference rates: a converted charge is then never paid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/observations/web-fact": { "post": { "operationId": "notarizeWebFact", "tags": [ "evidence" ], "summary": "Notarize a product endpoint with TLSNotary", "description": "Fetches the endpoint once over TLS with leg A as the TLSNotary notary (MPC-TLS, or Proxy-TLS when MPC-TLS fails), commits to the body or to the object around `anchor`, and returns the EIP-712 `WebFact` leg A signed with its attested key. Runs apart from any countersign and never delays one. An app acting for a user needs `evidence:write`.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "evidence:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebFactRequest" } } } }, "responses": { "201": { "description": "The signed WebFact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebFact" } } } }, "422": { "description": "The URL is refused, or its response is not a 200 the notary accepts", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many WebFacts today for this client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The session failed, or its WebFact did not verify", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No prover is configured, leg A has no admitted signer, or the rate limit store is unreachable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/purchases/{id}/chargeback": { "post": { "operationId": "chargeBackPurchase", "tags": [ "purchases" ], "summary": "Charge back a card purchase", "description": "Files a chargeback through the card issuer over a card purchase's settled transaction, with the purchase's Alibi as the cardholder's evidence: Visa 13.1 or Mastercard 4853 for an item not received, Visa 13.3 or 4853 for one not as described, Visa 10.4 or Mastercard 4837 for a charge the user did not authorize. What the chargeback returns is subtracted from any bond claim over the purchase, and no bond claim is paid while it is open. Only the mandate's owner files it, one at a time.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "not_received", "not_as_described", "unauthorized" ] }, "note": { "type": "string", "maxLength": 1000, "default": "" }, "amountMinor": { "type": "string", "pattern": "^[1-9][0-9]{0,15}$", "description": "Defaults to the settled amount, and cannot exceed it." } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Filed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardChargeback" } } } }, "404": { "description": "No such card purchase of this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The card is not settled yet, or a chargeback is already open", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The amount is above what was settled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The card issuer is not configured or unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tee/attestations": { "get": { "operationId": "listTeeAttestations", "tags": [ "tee" ], "summary": "Attested TEE signers", "description": "The signers whose countersignatures are accepted, each with the attestation it was admitted from, and the measurements the deployment publishes. A verifier checks the attestations itself.", "responses": { "200": { "description": "The admitted signers and the published measurements", "content": { "application/json": { "schema": { "type": "object", "properties": { "legs": { "type": "array", "items": { "$ref": "#/components/schemas/TeeLeg" } }, "measurements": { "type": "object", "properties": { "engineBuildId": { "type": "string" }, "tdx": { "type": "array", "items": { "type": "string" } }, "nitro": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "string", "description": "Where the Sigstore build provenance attested measurements.json is published; `gh attestation verify` checks it." } }, "required": [ "engineBuildId", "tdx", "nitro", "provenance" ] } }, "required": [ "legs", "measurements" ] } } } } } } }, "/v1/timestamps/{hash}": { "get": { "operationId": "getTimestamps", "tags": [ "timestamps" ], "summary": "RFC 3161 timestamps of a hash", "description": "The RFC 3161 tokens two independent TSAs issued over a log leaf hash (or another stamped hash). Each token's message imprint is the hash itself, so `openssl ts -verify -digest ` checks it.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The SHA-256 hash, 64 lowercase hex digits." }, "required": true, "description": "The SHA-256 hash, 64 lowercase hex digits.", "name": "hash", "in": "path" } ], "responses": { "200": { "description": "The tokens issued so far and the TSAs still pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string" }, "stamps": { "type": "array", "items": { "$ref": "#/components/schemas/Timestamp" } }, "pending": { "type": "array", "items": { "type": "string", "enum": [ "digicert", "sigstore", "freetsa", "sectigo" ] } } }, "required": [ "hash", "stamps", "pending" ] } } } }, "404": { "description": "The hash was never queued", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alibis/{id}.pdf": { "get": { "operationId": "getAlibiPdf", "tags": [ "alibis" ], "summary": "An Alibi as a PDF/A-3b", "description": "A one-page PDF/A-3b summary of the Alibi with a QR to its verify page and the bundle embedded as `.alibi`. Same readers, and the same public copy, as the bundle.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The Alibi id: the purchase's ULID." }, "required": true, "description": "The Alibi id: the purchase's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "The PDF has not changed" }, "404": { "description": "No Alibi with this id that the caller may read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alibis/{id}": { "get": { "operationId": "getAlibi", "tags": [ "alibis" ], "summary": "An Alibi bundle", "description": "The purchase's Alibi: its RFC 8785 bundle, readable by the mandate's user or, with `alibis:read`, by the client that uploaded the purchase's evidence; the Alibi of a live purchase, once its PayPal transaction is recorded, by anyone. Anyone else gets its public copy, whose mandate withholds the user's login id and risk data: their salted digests stay in the signed payload, so the copy verifies the same. It grows as timestamps, the capture and the on-chain anchor arrive; earlier sections never change.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The Alibi id: the purchase's ULID." }, "required": true, "description": "The Alibi id: the purchase's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The bundle", "content": { "application/vnd.keelson.alibi.v1+json": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "The bundle has not changed" }, "404": { "description": "No Alibi with this id that the caller may read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alibis/verify": { "post": { "operationId": "verifyAlibi", "tags": [ "alibis" ], "summary": "Verify an Alibi", "description": "Runs the browser verifier's algorithm on an Alibi bundle against the pinned trust roots and a public Arbitrum RPC. No authentication; the bundle is not stored.", "requestBody": { "required": true, "content": { "application/vnd.keelson.alibi.v1+json": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlibiReport" } } } }, "400": { "description": "Not an Alibi bundle; `pointer` names the failing value", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The body is over 1 MiB", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "The body is not an Alibi bundle's media type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/alibis/{id}/receipt": { "get": { "operationId": "getAlibiReceipt", "tags": [ "alibis" ], "summary": "The public receipt of an Alibi", "description": "What the public log already publishes about an Alibi: its leaf, inclusion proof, anchor and timestamps. No authentication.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The Alibi id: the purchase's ULID." }, "required": true, "description": "The Alibi id: the purchase's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlibiReceipt" } } } }, "404": { "description": "No Alibi with this id that the caller may read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/anonymous-mandates/{mandateHash}": { "get": { "operationId": "getAnonymousMandate", "tags": [ "mandates" ], "summary": "Proof that a registered user signed a mandate", "description": "The C3 `anonymous_mandate` zero-knowledge proof of the mandate whose passkey challenge is `mandateHash`, the `mandateHash` of its countersigns: a passkey in Keelson's registered-user tree signed it, and the mandate's commitment names that passkey. It shows neither the user nor the key, so it needs no authentication. Verify it with bb.js against the C3 key or with `eth_call` on `verifier`, and check that `user_set_root` is published in the `RegisteredUserSet` contract, as `verifyAnonymousMandate` in `@keelson/alibi/verify` does.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "required": true, "name": "mandateHash", "in": "path" } ], "responses": { "200": { "description": "The proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousMandate" } } } }, "404": { "description": "No proof for this mandate yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/anonymous-purchases/{id}": { "get": { "operationId": "getAnonymousPurchase", "tags": [ "purchases" ], "summary": "Proof that a purchase was within a mandate a registered user signed", "description": "One zero-knowledge proof that composes the purchase's C1 proof (the countersigned cart satisfies the mandate) with its mandate's C3 proof (a registered user's passkey, the one the mandate names, signed it) by recursion. It shows neither the mandate nor the user. Its public inputs are the countersign's cart fields, `C_m` and `M`, which link the purchases of one mandate: anyone holding the purchase id can read it.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousPurchase" } } } }, "404": { "description": "No composed proof for this purchase yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/user-set/roots/{root}": { "get": { "operationId": "getUserSetRoot", "tags": [ "mandates" ], "summary": "A root of the registered-user tree", "description": "Whether `root` is, or was, the root of Keelson's registered-user tree: the Poseidon2 Merkle tree of every registered passkey's `user_key_hash`. A C3 proof under any root listed here was made by a registered user, who is hidden among the `size` users of that root. Roots stay valid after a passkey is removed. Keelson's relayer publishes every root to the `RegisteredUserSet` contract, which is what a verifier trusts; this route is a convenience.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "required": true, "name": "root", "in": "path" } ], "responses": { "200": { "description": "The root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSetRoot" } } } }, "404": { "description": "No such root", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/engine-proofs/{id}": { "get": { "operationId": "getEngineProof", "tags": [ "purchases" ], "summary": "SP1 proof of a purchase's engine evaluation", "description": "For a disputed purchase, an SP1 Groth16 proof that the engine's own canonicalizer and Cedar evaluation, run again in the SP1 zkVM over the purchase's stored inputs, give the `evalHash` both TEE legs signed, and the transaction that verified it on chain through Succinct's SP1 verifier gateway. It holds only hashes and the proof, so it needs no authentication.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineProof" } } } }, "404": { "description": "No dispute over this purchase, or no inputs kept to prove it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/disputes/{id}": { "get": { "operationId": "getDispute", "tags": [ "Disputes" ], "summary": "A dispute's attribution", "description": "Where a PayPal dispute over a Keelson purchase stands: the party at fault, the `Verdict` both TEE legs signed, the time from the dispute's arrival to its verdict, and the operator's amber commitment with any conviction of it. No authentication; it holds no personal data, so what the operator attested is left out.", "parameters": [ { "schema": { "type": "string", "pattern": "^PP-[A-Z]-[0-9A-Za-z-]{1,40}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The dispute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeStatus" } } } }, "404": { "description": "No dispute with this id over a Keelson purchase", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/passkeys": { "get": { "operationId": "listPasskeys", "tags": [ "passkeys" ], "summary": "List the signed-in user's passkeys", "description": "The credentials a mandate can be signed with, oldest first.", "security": [ { "session": [] } ], "responses": { "200": { "description": "The passkeys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkeys" } } } }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/passkeys/{id}": { "delete": { "operationId": "deletePasskey", "tags": [ "passkeys" ], "summary": "Remove one of the signed-in user's passkeys", "description": "The passkey can no longer sign in or sign mandates, and the user's other sessions end. It takes a sign-in within the last 10 minutes. A user keeps at least one passkey, so the last one is not removed, and a passkey stays while a mandate it signed is still being proved.", "security": [ { "session": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Not signed in", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is older than 10 minutes", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such passkey of this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The user's last passkey, or one whose mandate is still being proved", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators": { "post": { "operationId": "linkOperator", "tags": [ "operators" ], "summary": "Link an ERC-8004 agent as an operator", "description": "Binds the agent's `cnf` key to its ERC-8004 identity once its owner or `agentWallet` signs `OperatorLink`. The owner of an agent that is already linked re-links it, after a transfer for example.", "security": [ { "oauth2": [ "operators:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkOperator" } } } }, "responses": { "201": { "description": "The operator is linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not signed by the agent's owner or agent wallet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such agent in the Identity registry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The agent id is linked on another registry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or past its deadline", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The chain cannot be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/by-address/{address}/registration.json": { "get": { "operationId": "getOwnerRegistration", "tags": [ "operators" ], "summary": "Registration file of an owner's agents", "description": "The ERC-8004 registration file listing every linked agent whose owner in the Identity registry is `address` now.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "required": true, "name": "address", "in": "path" } ], "responses": { "200": { "description": "The registration file", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "404": { "description": "The address owns no linked agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The chain cannot be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{chainId}/{agentId}/registration.json": { "get": { "operationId": "getAgentRegistration", "tags": [ "operators" ], "summary": "Registration file of an agent", "description": "The ERC-8004 registration file of the agent's current owner, listing every linked agent it owns.", "parameters": [ { "schema": { "type": "string", "enum": [ "42161", "421614", "11155111" ], "description": "An EIP-155 chain id." }, "required": true, "description": "An EIP-155 chain id.", "name": "chainId", "in": "path" }, { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The registration file", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "404": { "description": "Not a linked agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The chain cannot be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{chainId}/{agentId}/bond": { "get": { "operationId": "getAgentBond", "tags": [ "operators" ], "summary": "Bond, reputation and validations of an agent", "description": "Read on-chain in one multicall: the vault's `bonds(agentId)`, the Reputation registry's `getSummary(agentId, [reporter, relayer], \"keelson\", \"\")` (coverage outcomes, and faults the bond did not pay) and its `\"slash\"` count, and the validation registry's `getSummary(agentId, [VerdictVerifier], \"\")`.", "parameters": [ { "schema": { "type": "string", "enum": [ "42161", "421614", "11155111" ], "description": "An EIP-155 chain id." }, "required": true, "description": "An EIP-155 chain id.", "name": "chainId", "in": "path" }, { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The bond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorBond" } } } }, "404": { "description": "Keelson is not deployed on the chain", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The chain cannot be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/mandates": { "get": { "operationId": "listOperatorMandates", "tags": [ "operators" ], "summary": "The active mandates naming the operator", "description": "Lists the active mandates whose operator is `agentId`, with their open mandates and holds, so that the operator's agent can buy under them. Only the OAuth client that linked the operator (`POST /v1/operators`) reads them; any other caller gets 404. An app acting for a user (`mandates:request`) reads only the mandates naming `agentId` that this user approved for it.", "security": [ { "oauth2": [ "countersign:write" ] }, { "oauth2": [ "mandates:request" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The operator's active mandates, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "mandates": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorMandate" } } }, "required": [ "mandates" ] } } } }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The token lacks countersign:write", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No operator this client linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/mandates/{mandateId}/runs": { "post": { "operationId": "announceRun", "tags": [ "operators" ], "summary": "Announce an agent run under a mandate", "description": "Tells the mandate's owner that the operator's agent started or ended shopping under the mandate, with the live view of its browser, as an `agent.run` event on the owner's `mandate:` stream. Only the OAuth client that linked the operator announces runs, on its active mandates.", "security": [ { "oauth2": [ "countersign:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 26, "maxLength": 26 }, "required": true, "name": "mandateId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "responses": { "202": { "description": "Published to the mandate's owner" }, "401": { "description": "No valid access token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The token lacks countersign:write", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active mandate of an operator this client linked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or not a Kernel live view", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/grade": { "get": { "operationId": "getTrustGrade", "tags": [ "operators" ], "summary": "Trust grade, premium and bond of an operator", "description": "Recomputed whenever a coverage or a verdict of the operator, or the nightly calibration, changes it. Public.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The operator's ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The operator's ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The grade", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustGrade" } } } }, "404": { "description": "Not a linked operator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Nothing to price the operator's losses from yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No finished red-team campaign to calibrate from", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/grade/stream": { "get": { "operationId": "streamTrustGrade", "tags": [ "operators" ], "summary": "Follow an operator's trust grade", "description": "Server-sent events: a `grade` event with the current grade, and another each time a coverage, a verdict or a calibration changes it. Public.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The operator's ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The operator's ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "An event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "description": "Not a linked operator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Nothing to price the operator's losses from yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No calibration yet, or too many open streams", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/feedback/{coverageId}": { "get": { "operationId": "getFeedback", "tags": [ "reputation" ], "summary": "Feedback file of a rated coverage", "description": "The off-chain feedback file the `feedbackURI` of Keelson's ERC-8004 feedback points to, built from the reporter's `CoverageRated` log and the Reputation registry's `NewFeedback` log of the same transaction.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The coverage id, 32 bytes of lowercase hex." }, "required": true, "description": "The coverage id, 32 bytes of lowercase hex.", "name": "coverageId", "in": "path" } ], "responses": { "200": { "description": "The feedback file", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "404": { "description": "The coverage was not rated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/validations/{requestHash}": { "get": { "operationId": "getValidation", "tags": [ "validations" ], "summary": "Validation request of a countersign", "description": "What the `requestURI` of a Keelson validation request points to: the countersign whose EIP-712 digest, under the VerdictVerifier domain, is `requestHash`.", "parameters": [ { "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The countersign digest, 32 bytes of lowercase hex." }, "required": true, "description": "The countersign digest, 32 bytes of lowercase hex.", "name": "requestHash", "in": "path" } ], "responses": { "200": { "description": "The validation request", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationRequest" } } } }, "404": { "description": "No countersign has this digest", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/bonds/{agentId}/deposits": { "post": { "operationId": "depositBond", "tags": [ "bonds" ], "summary": "Deposit PYUSD into an operator's bond, gasless", "description": "Relays `depositWithAuthorization` (EIP-3009) or `depositWithPermit` (EIP-2612) to the bond vault; Keelson pays the gas. The same authorization is sent once, whatever the idempotency key. An `operators:write` client sends either; the operator's own session (EIP-4361, from the operator console) sends a permit whose `owner` is a wallet it signed in with that owns the agent.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BondDeposit" } } } }, "responses": { "200": { "description": "Confirmed on-chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "202": { "description": "Sent and not yet confirmed; poll `Location`", "headers": { "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "No valid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The same call was submitted with other arguments", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or the call reverts: `error` names the contract's custom error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The relayer cannot send now: chain unavailable, gas price cap or low balance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/bonds/{agentId}/withdrawals": { "post": { "operationId": "queueBondWithdrawal", "tags": [ "bonds" ], "summary": "Queue a bond withdrawal, gasless", "description": "Relays `requestWithdrawal`; the funds stay slashable until the withdrawal delay ends and it is completed.", "security": [ { "oauth2": [ "operators:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BondWithdrawal" } } } }, "responses": { "200": { "description": "Confirmed on-chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "202": { "description": "Sent and not yet confirmed; poll `Location`", "headers": { "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "No valid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The same call was submitted with other arguments", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or the call reverts: `error` names the contract's custom error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The relayer cannot send now: chain unavailable, gas price cap or low balance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/bonds/withdrawals/{chainId}/{withdrawalId}/complete": { "post": { "operationId": "completeBondWithdrawal", "tags": [ "bonds" ], "summary": "Complete a queued withdrawal, gasless", "description": "Relays `completeWithdrawal`, which anyone may call once the delay ended; it pays only the signed recipient.", "security": [ { "session": [] }, { "oauth2": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "42161", "421614" ] }, "required": true, "name": "chainId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9]\\d{0,19}$" }, "required": true, "name": "withdrawalId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Confirmed on-chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "202": { "description": "Sent and not yet confirmed; poll `Location`", "headers": { "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "No valid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The same call was submitted with other arguments", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or the call reverts: `error` names the contract's custom error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The relayer cannot send now: chain unavailable, gas price cap or low balance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/log/bonds": { "get": { "operationId": "listLogBonds", "tags": [ "log" ], "summary": "Log equivocation bonds", "description": "The PYUSD bonds on the log keys, on Arbitrum Sepolia. Two checkpoints signed by a bond's key that state different roots for one size pay its whole balance to whoever submits them (`LogBond.proveEquivocation`). Each bond reports its balance and, once slashed, the equivocation and its transaction.", "responses": { "200": { "description": "Every deployed bond", "content": { "application/json": { "schema": { "type": "object", "properties": { "bonds": { "type": "array", "items": { "$ref": "#/components/schemas/LogBond" } } }, "required": [ "bonds" ] } } } }, "503": { "description": "This server does not read Arbitrum Sepolia", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/payout-address": { "post": { "operationId": "setPayoutAddress", "tags": [ "merchants" ], "summary": "Set a merchant's payout address, gasless", "description": "Relays `setPayoutAddress` to the bond vault; Keelson pays the gas.", "security": [ { "oauth2": [ "merchants:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAddress" } } } }, "responses": { "200": { "description": "Confirmed on-chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "202": { "description": "Sent and not yet confirmed; poll `Location`", "headers": { "Location": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "No valid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The same call was submitted with other arguments", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid, or the call reverts: `error` names the contract's custom error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The relayer cannot send now: chain unavailable, gas price cap or low balance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/{merchantId}/settlement": { "put": { "operationId": "setSettlement", "tags": [ "merchants" ], "summary": "Choose how a merchant is paid when a dispute goes its way", "description": "Applies to verdicts signed afterwards: the rail decides the payee the TEE legs sign into the `Verdict`. The merchant signs the choice, as it signs its on-chain payout address. Sent by a client with `merchants:write` or by the merchant's own session.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedSettlementPreference" } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "pyusd", "paypal" ], "description": "`pyusd`: slashes and warranties pay the merchant in PYUSD on chain. `paypal`: they pay Keelson's treasury, and Keelson sends the merchant a PayPal Payout in USD." }, "paypal_receiver": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "string", "pattern": "^[A-Z0-9]{13}$" } ], "description": "The PayPal account paid: an email address or a PayPal account id." } }, "required": [ "rail" ] } } } }, "403": { "description": "The signature, or the session, is not the merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such merchant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The nonce is not higher than the one of the merchant's last choice", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getSettlement", "tags": [ "merchants" ], "summary": "How a merchant is paid when a dispute goes its way", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "responses": { "200": { "description": "The current choice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSettlement" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/me": { "get": { "operationId": "getMerchant", "tags": [ "merchants" ], "summary": "The merchant signed in", "responses": { "200": { "description": "The merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSelf" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/{merchantId}/disputes": { "get": { "operationId": "listMerchantDisputes", "tags": [ "merchants" ], "summary": "A merchant's disputes and their verdicts", "description": "The latest 500 PayPal disputes over the merchant's Keelson purchases, newest first.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "responses": { "200": { "description": "The disputes", "content": { "application/json": { "schema": { "type": "object", "properties": { "disputes": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantDispute" } } }, "required": [ "disputes" ] } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/{merchantId}/orders": { "get": { "operationId": "listMerchantOrders", "tags": [ "merchants" ], "summary": "The agent purchases at a merchant", "description": "The latest 100 purchases agents asked Keelson to countersign at the merchant, newest first: the ones it allowed and the ones it blocked, with the dispute over each.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "responses": { "200": { "description": "The orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrder" } } }, "required": [ "orders" ] } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/{merchantId}/evaluations": { "get": { "operationId": "listMerchantEvaluations", "tags": [ "merchants" ], "summary": "Field-level evaluations of the agents that shopped at a merchant", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "responses": { "200": { "description": "The evaluations, as columns and rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantEvaluations" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/merchants/{merchantId}/assistant": { "post": { "operationId": "askMerchantAssistant", "tags": [ "merchants" ], "summary": "One streamed model turn for the merchant console's agents", "description": "Streams the Messages API events as newline-delimited JSON (the Anthropic SDK's `MessageStream.toReadableStream`). Each merchant has a daily budget; once it is spent the turn runs on `claude-haiku-5-5`, named in `Keelson-Model`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "merchantId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantTurn" } } } }, "responses": { "200": { "description": "The turn's events", "headers": { "keelson-model": { "schema": { "type": "string", "enum": [ "claude-opus-5-5", "claude-haiku-5-5" ] }, "required": true } }, "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session is not this merchant's", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many turns, or today's budget is spent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The model provider refused the turn", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No model provider configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/me": { "get": { "operationId": "listOwnedOperators", "tags": [ "operators" ], "summary": "The operators the session's wallet owns", "description": "The linked agents whose owner or agent wallet in the Identity registry is a wallet the session signed in with (EIP-4361). A wallet signs in if it owned a linked agent when the agent was linked; ownership is then read on chain on every operator route.", "responses": { "200": { "description": "The operators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorSelf" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session's wallets do not own the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/coverages/rows": { "post": { "operationId": "getCoverageRows", "tags": [ "operators" ], "summary": "A block of the operator's coverages, for AG Grid's server-side row model", "description": "The operator's covered purchases with their latest dispute and verdict, filtered, sorted and paged as AG Grid asks. `rowCount` is the filtered total. A read: no idempotency key.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The operator's ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The operator's ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageRowsRequest" } } } }, "responses": { "200": { "description": "The block", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageRow" } }, "rowCount": { "type": "integer" } }, "required": [ "rows", "rowCount" ] } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session's wallets do not own the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A filter the column does not have", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/coverages/daily": { "get": { "operationId": "getDailyCoverages", "tags": [ "operators" ], "summary": "The operator's coverages per day", "description": "Per UTC day: coverages locked, the amount covered, premiums, and incidents.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The operator's ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The operator's ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The days, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageDay" } } }, "required": [ "days" ] } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session's wallets do not own the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/operators/{agentId}/grid-query": { "post": { "operationId": "queryCoverageGrid", "tags": [ "operators" ], "summary": "Turn a sentence into the coverage grid's state", "description": "The backend of AG Grid's AI Toolkit: Claude answers with structured output in the grid's own state schema. The console's daily model budget applies; past it the query runs on `claude-haiku-5-5`.", "parameters": [ { "schema": { "type": "string", "pattern": "^(0|[1-9]\\d{0,19})$", "description": "The operator's ERC-8004 agent id, a decimal integer." }, "required": true, "description": "The operator's ERC-8004 agent id, a decimal integer.", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GridQuery" } } } }, "responses": { "200": { "description": "The new state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GridAnswer" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The session's wallets do not own the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many queries, or today's budget is spent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The model did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No model provider configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/purchases/{id}/tracking": { "post": { "operationId": "recordTracking", "tags": [ "purchases" ], "summary": "Record a purchase's shipment and its delivery", "description": "Adds the tracker to the PayPal order (Orders v2) and, once delivered, records the delivery with PayPal's Add Tracking API. Idempotent per tracking number.", "security": [ { "oauth2": [ "merchants:write" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tracking" } } } }, "responses": { "200": { "description": "Recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "tracker_id": { "type": "string" } }, "required": [ "state", "tracker_id" ] } } } }, "404": { "description": "No such purchase", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The purchase was not captured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "PayPal refused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "PayPal unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/transactions/{id}": { "get": { "operationId": "getTransaction", "tags": [ "transactions" ], "summary": "A relayed transaction", "description": "A transaction the Keelson relayer sent: its status, hash, receipt fields and explorer link. Final records are immutable.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The transaction", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "404": { "description": "No such transaction", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/redteam/campaigns": { "get": { "operationId": "listRedTeamCampaigns", "tags": [ "red team" ], "summary": "Red-team campaigns", "description": "The latest red-team campaigns, newest first. Public.", "responses": { "200": { "description": "Up to 20 campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "attacks": { "type": "integer" } }, "required": [ "id", "startedAt", "finishedAt", "attacks" ] } } }, "required": [ "campaigns" ] } } } } } } }, "/v1/redteam/campaigns/{id}/ledger": { "get": { "operationId": "getRedTeamLedger", "tags": [ "red team" ], "summary": "A campaign's ledger", "description": "The campaign's hash-chained JSON Lines ledger, byte for byte: the header, one line per attack and, once finished, the summary. Each line is RFC 8785 JSON whose `prev` is the SHA-256 of `keelson/redteam/v1 ‖ 0x00 ‖ previous line`. Public.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "The campaign's ULID." }, "required": true, "description": "The campaign's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The ledger so far", "content": { "application/jsonl": { "schema": { "type": "string" } } } }, "404": { "description": "No such campaign", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/redteam/campaigns/{id}/scoreboard": { "get": { "operationId": "getRedTeamScoreboard", "tags": [ "red team" ], "summary": "A campaign's scoreboard", "description": "Agent ASR, Keelson's escape rate with its Clopper-Pearson 95 % interval, false blocks and utility under attack with Wilson 95 % intervals, per backbone and split, computed from the ledger alone. The body is RFC 8785 JSON: recomputing it from the ledger gives the same bytes. Public.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "The campaign's ULID." }, "required": true, "description": "The campaign's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The scoreboard of the ledger so far", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "404": { "description": "No such campaign", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/redteam/campaigns/{id}/scoreboard/stream": { "get": { "operationId": "streamRedTeamScoreboard", "tags": [ "red team" ], "summary": "Follow a campaign's scoreboard", "description": "Server-sent events: a `scoreboard` event with the current scoreboard, another each time the ledger grows, and `end` once the campaign is finished. Public.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "The campaign's ULID." }, "required": true, "description": "The campaign's ULID.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "An event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "description": "No such campaign", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Too many open streams", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/judge/sessions": { "post": { "operationId": "openJudgeSession", "tags": [ "judge" ], "summary": "Open a Judge Mode session", "description": "Creates a judge: a tenant with no email, no account and no key, signed in with a session cookie until the nightly reset after 12 hours. A judge reads the demo merchant's console (no changes), walks the tour, and can sign its own mandates with a passkey like any user. Five per hour per address, and a cap a day over every address that a judge with the invite is counted apart from.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "type": "string", "maxLength": 256, "description": "The invite from the hackathon's testing instructions." } } } } } }, "responses": { "201": { "description": "The judge, signed in (the session cookie is set)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeSession" } } } }, "403": { "description": "Not called from the app's origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already signed in as someone else", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many judges", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Sign-in is not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/judge/tour": { "get": { "operationId": "getJudgeTour", "tags": [ "judge" ], "summary": "What the Judge Mode tour shows", "description": "The newest real records on this deployment: the demo operator's latest mandate with a captured purchase (its card and every purchase under it, blocked ones included), the latest sandbox dispute with a verdict, and the latest finished red-team campaign. Judges only.", "responses": { "200": { "description": "The tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeTour" } } } }, "401": { "description": "No session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not a judge", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": {} }