{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://mandateshield.com/schemas/purchase-envelope.json", "title": "Mandate Execution Boundary Purchase Envelope", "description": "Protocol-neutral facts used to evaluate an AI-agent purchase immediately before execution.", "type": "object", "additionalProperties": true, "required": [ "protocol", "mandate_id", "agent_id", "merchant_id", "amount", "idempotency_key" ], "properties": { "protocol": { "type": "string", "enum": [ "AP2", "TAP", "UCP", "X402", "MPP", "ACP", "CUSTOM" ], "description": "Source protocol or CUSTOM for a normalized envelope." }, "mandate_id": { "type": "string", "minLength": 1, "description": "Stable identifier for the user-approved authority." }, "agent_id": { "type": "string", "minLength": 1, "description": "Stable identifier for the acting AI agent." }, "merchant_id": { "type": "string", "minLength": 1, "description": "Stable identifier for the final seller or payee." }, "payee_identity": { "type": "object", "additionalProperties": false, "required": [ "profile", "provider", "merchant_id", "binding", "verification" ], "properties": { "profile": { "const": "MANDATESHIELD_PAYEE_IDENTITY_V1" }, "provider": { "type": "string", "enum": [ "X402", "MPP", "STRIPE", "CUSTOM" ] }, "merchant_id": { "type": "string", "minLength": 1, "maxLength": 240 }, "binding": { "type": "object" }, "verification": { "type": "object", "additionalProperties": false, "required": [ "method", "verifier", "evidence_ref" ], "properties": { "method": { "type": "string", "enum": [ "TRUSTED_MERCHANT_MAPPING", "TLS_SERVICE_ORIGIN", "STRIPE_ACCOUNT_CONFIGURATION", "HTTPS_WELL_KNOWN" ] }, "verifier": { "type": "string", "minLength": 1, "maxLength": 240 }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } } } }, "oneOf": [ { "properties": { "provider": { "const": "X402" }, "binding": { "type": "object", "additionalProperties": false, "required": [ "network", "pay_to" ], "properties": { "network": { "type": "string", "minLength": 1, "maxLength": 240 }, "pay_to": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "verification": { "type": "object", "additionalProperties": false, "required": [ "method", "verifier", "evidence_ref" ], "properties": { "method": { "const": "TRUSTED_MERCHANT_MAPPING" }, "verifier": { "type": "string", "minLength": 1, "maxLength": 240 }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } } } } }, { "properties": { "provider": { "const": "MPP" }, "binding": { "type": "object", "additionalProperties": false, "required": [ "service_origin", "method" ], "properties": { "service_origin": { "type": "string", "pattern": "^https://[^/?#]+$" }, "method": { "type": "string", "pattern": "^[a-z]+$" } } }, "verification": { "type": "object", "additionalProperties": false, "required": [ "method", "verifier", "evidence_ref" ], "properties": { "method": { "const": "TLS_SERVICE_ORIGIN" }, "verifier": { "type": "string", "minLength": 1, "maxLength": 240 }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } } } } }, { "properties": { "provider": { "const": "STRIPE" }, "binding": { "type": "object", "additionalProperties": false, "required": [ "connected_account_id", "merchant_account_id" ], "properties": { "connected_account_id": { "type": "string", "pattern": "^acct_[A-Za-z0-9_]{8,240}$" }, "merchant_account_id": { "type": "string", "pattern": "^acct_[A-Za-z0-9_]{8,240}$" } } }, "verification": { "type": "object", "additionalProperties": false, "required": [ "method", "verifier", "evidence_ref" ], "properties": { "method": { "const": "STRIPE_ACCOUNT_CONFIGURATION" }, "verifier": { "type": "string", "minLength": 1, "maxLength": 240 }, "evidence_ref": { "type": "string", "pattern": "^urn:stripe:connected-account:acct_[A-Za-z0-9_]{8,240}$" } } } } }, { "properties": { "provider": { "const": "CUSTOM" }, "binding": { "type": "object", "additionalProperties": false, "required": [ "service_origin", "provider_id" ], "properties": { "service_origin": { "type": "string", "pattern": "^https://[^/?#]+$" }, "provider_id": { "type": "string", "minLength": 1, "maxLength": 240 } } }, "verification": { "type": "object", "additionalProperties": false, "required": [ "method", "verifier", "evidence_ref" ], "properties": { "method": { "const": "HTTPS_WELL_KNOWN" }, "verifier": { "type": "string", "minLength": 1, "maxLength": 240 }, "evidence_ref": { "type": "string", "format": "uri", "pattern": "^https://[^/?#]+/\\.well-known/mandateshield-payee\\.json$" } } } } } ], "description": "Versioned canonical payee identity bound into the signed purchase envelope. The model records exact provider identifiers and verification evidence; it does not independently validate an external registry, TLS session, provider account or domain-control document." }, "amount": { "type": "object", "additionalProperties": false, "oneOf": [ { "required": [ "value", "currency" ] }, { "required": [ "atomic_units", "asset_decimals" ] } ], "properties": { "value": { "type": "number", "exclusiveMinimum": 0 }, "minor_units": { "type": "integer", "minimum": 1, "description": "Optional exact integer amount in the currency's minor unit." }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "Three-letter ISO currency code." }, "atomic_units": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,77})$", "description": "Exact integer atomic-asset amount. This string is authoritative for X402." }, "asset_decimals": { "type": "integer", "minimum": 0, "maximum": 30 } } }, "limits": { "type": "object", "properties": { "max_amount": { "type": "number", "exclusiveMinimum": 0 }, "max_amount_minor": { "type": "integer", "exclusiveMinimum": 0 }, "max_atomic_units": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "asset_decimals": { "type": "integer", "minimum": 0, "maximum": 30 }, "currencies": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[A-Za-z]{3}$" } }, "merchants": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "assets": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "networks": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "resources": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } }, "oneOf": [ { "required": [ "currencies", "merchants" ], "anyOf": [ { "required": [ "max_amount_minor" ] }, { "required": [ "max_amount" ] } ] }, { "required": [ "max_atomic_units", "asset_decimals", "assets", "networks", "resources", "merchants" ] } ], "description": "Sandbox analysis policy. Live v2 ignores caller policy and loads the registered mandate." }, "asset_id": { "type": "string", "minLength": 1, "description": "Exact token or asset identifier; required for atomic X402 payments." }, "network": { "type": "string", "minLength": 1, "description": "Exact network or chain identifier; required for atomic X402 payments." }, "resource": { "type": "string", "minLength": 1, "description": "Exact paid resource identifier; required for atomic X402 payments." }, "http_request": { "type": "object", "additionalProperties": false, "required": [ "profile", "url", "method", "body_sha256", "headers_sha256", "redirect_policy" ], "properties": { "profile": { "const": "MANDATESHIELD_X402_V2_EXACT_EIP3009_V1" }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE" ] }, "body_sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "headers_sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "redirect_policy": { "const": "ERROR" } }, "description": "Optional signed HTTP action projection used by the narrow first-party x402 v2 exact/EIP-3009 Gate adapter." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9._:~-]+$", "description": "Unique identifier for this intended payment attempt." }, "intent_hash": { "type": "string" }, "checkout_hash": { "type": "string", "minLength": 1, "description": "Digest or stable identifier for the exact final checkout." }, "user_consent": { "type": "boolean" }, "credential_binding": { "type": "string" }, "purpose": { "type": "string", "description": "Non-sensitive plain-language purchase purpose." } } }