{
	"openapi": "3.0.3",
	"info": {
		"title": "Bruce Public API",
		"version": "2.0.0",
		"description": "Merchant + agent control plane: checkout, invoices, offerings, escrow, verification, webhooks, and agent payments (instant, escrow, x402, A2A, AP2). Auth: X-Api-Key bk_live_… / bk_agent_live_… or Bearer bat_…. Docs: https://docs.bruce.money"
	},
	"servers": [{ "url": "https://api.bruce.money" }],
	"security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
	"components": {
		"securitySchemes": {
			"ApiKeyAuth": {
				"type": "apiKey",
				"in": "header",
				"name": "X-Api-Key"
			},
			"BearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"description": "bk_live_ API key or bat_ OAuth access token"
			}
		},
		"parameters": {
			"IdempotencyKey": {
				"name": "Idempotency-Key",
				"in": "header",
				"required": false,
				"schema": { "type": "string", "maxLength": 128 },
				"description": "Required for money-moving POSTs (escrow release/dispute, verification confirm)."
			}
		},
		"schemas": {
			"Error": {
				"type": "object",
				"required": ["error", "code", "requestId"],
				"properties": {
					"error": { "type": "string" },
					"code": {
						"type": "string",
						"enum": [
							"invalid_request",
							"unauthorized",
							"forbidden",
							"not_found",
							"rate_limited",
							"idempotency_conflict",
							"kyb_rejected",
							"missing_scope",
							"confirm_required",
							"idempotency_required",
							"internal"
						]
					},
					"requestId": { "type": "string" },
					"details": {}
				}
			},
			"FeeQuote": {
				"type": "object",
				"properties": {
					"source": { "type": "string", "enum": ["checkout", "invoice", "escrow", "p2p"] },
					"grossAmount": { "type": "string" },
					"feeAmount": { "type": "string" },
					"netAmount": { "type": "string" },
					"bps": { "type": "integer" },
					"currency": { "type": "string", "enum": ["USDC"] }
				}
			},
			"CheckoutSession": {
				"type": "object",
				"properties": {
					"id": { "type": "string", "format": "uuid" },
					"amount": { "type": "string" },
					"description": { "type": "string" },
					"status": { "type": "string" },
					"settlement": { "type": "string", "enum": ["escrow"] },
					"orderId": { "type": "string", "nullable": true },
					"shopDomain": { "type": "string", "nullable": true },
					"escrowId": { "type": "string", "nullable": true },
					"escrowTemplateId": {
						"type": "string",
						"enum": ["freelance", "physical", "digital", "custom"]
					},
					"payUrl": { "type": "string", "format": "uri" },
					"redirectUrl": { "type": "string", "nullable": true },
					"metadata": { "type": "object", "nullable": true },
					"fee": { "$ref": "#/components/schemas/FeeQuote" },
					"createdAt": { "type": "string" }
				}
			},
			"WebhookEvent": {
				"type": "string",
				"enum": [
					"checkout.funded",
					"checkout.accepted",
					"checkout.released",
					"checkout.disputed",
					"checkout.refunded",
					"checkout.cancelled",
					"checkout.paid"
				]
			}
		}
	},
	"paths": {
		"/api/v1/me": {
			"get": {
				"summary": "Identity, org, scopes, verification snapshot",
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/checkout-sessions": {
			"get": {
				"summary": "List checkout sessions",
				"parameters": [
					{ "name": "limit", "in": "query", "schema": { "type": "integer" } },
					{ "name": "starting_after", "in": "query", "schema": { "type": "string" } }
				],
				"responses": { "200": { "description": "OK" } }
			},
			"post": {
				"summary": "Create escrow checkout session",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "Created" } }
			}
		},
		"/api/v1/checkout-sessions/{id}": {
			"get": {
				"summary": "Get checkout session",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } }
			}
		},
		"/api/v1/invoices": {
			"get": { "summary": "List invoices", "responses": { "200": { "description": "OK" } } },
			"post": {
				"summary": "Create invoice",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "Created" } }
			}
		},
		"/api/v1/invoices/{id}": {
			"get": {
				"summary": "Get invoice",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/invoices/{id}/send": {
			"post": {
				"summary": "Send draft invoice",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "$ref": "#/components/parameters/IdempotencyKey" }
				],
				"responses": { "200": { "description": "Sent" } }
			}
		},
		"/api/v1/offerings": {
			"get": { "summary": "List offerings", "responses": { "200": { "description": "OK" } } },
			"post": { "summary": "Create offering", "responses": { "200": { "description": "Created" } } }
		},
		"/api/v1/offerings/{id}": {
			"get": {
				"summary": "Get offering",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" } }
			},
			"patch": {
				"summary": "Update offering",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/escrows": {
			"get": { "summary": "List escrows", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/escrows/{id}": {
			"get": {
				"summary": "Get escrow",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/escrows/{id}/release": {
			"post": {
				"summary": "Release escrow (buyer). Requires confirm:true + Idempotency-Key + txHash.",
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/escrows/{id}/dispute": {
			"post": {
				"summary": "Dispute escrow. Requires confirm:true + Idempotency-Key + txHash.",
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/escrows/{id}/accept": {
			"post": { "summary": "Seller accept", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/escrows/{id}/cancel": {
			"post": { "summary": "Buyer cancel", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/escrows/{id}/decline": {
			"post": { "summary": "Seller decline", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/escrows/{id}/mark-delivered": {
			"post": { "summary": "Seller mark delivered", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/verification": {
			"get": { "summary": "KYB/verification status", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/verification/checkout": {
			"post": { "summary": "Start verification payment", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/verification/confirm": {
			"post": {
				"summary": "Confirm verification USDC payment",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/verification/start": {
			"post": {
				"summary": "Start Didit session; returns verificationUrl for human completion",
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/webhook-endpoints": {
			"get": { "summary": "Get org webhook endpoint", "responses": { "200": { "description": "OK" } } },
			"put": {
				"summary": "Upsert webhook URL; optional rotateSecret returns plaintext once",
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/webhook-deliveries": {
			"get": { "summary": "List webhook deliveries", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/webhook-deliveries/{id}/retry": {
			"post": {
				"summary": "Retry delivery",
				"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/fees/quote": {
			"get": {
				"summary": "Fee quote",
				"parameters": [
					{ "name": "source", "in": "query", "schema": { "type": "string" } },
					{ "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } }
				],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/agent": {
			"get": { "summary": "Agent identity + policy (agent keys)", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/balance": {
			"get": { "summary": "Owner USDC balance for agent", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/payments": {
			"post": {
				"summary": "Instant agent USDC payment",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "OK" }, "403": { "description": "Policy/signer" } }
			}
		},
		"/api/v1/agent-escrows": {
			"post": {
				"summary": "Create escrow as agent buyer",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/mandates": {
			"get": { "summary": "List AP2 mandates", "responses": { "200": { "description": "OK" } } },
			"post": { "summary": "Create AP2 mandate", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/x402/challenge": {
			"get": { "summary": "HTTP 402 payment challenge (Polygon USDC)", "responses": { "402": { "description": "Payment Required" } } }
		},
		"/api/v1/x402/settle": {
			"post": {
				"summary": "Settle x402 payment via agent policy",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "OK" } }
			}
		},
		"/api/v1/a2a/agent-card": {
			"get": { "summary": "A2A Agent Card", "responses": { "200": { "description": "OK" } } }
		},
		"/api/v1/a2a/payment-submitted": {
			"post": {
				"summary": "A2A-x402 payment submission",
				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
				"responses": { "200": { "description": "OK" } }
			}
		}
	}
}