{
 "openapi": "3.1.0",
 "info": {
  "title": "agent-bev.ai",
  "version": "0.1.2",
  "summary": "Agentic B2B hub for beer, wine and spirits across Europe.",
  "description": "The HTTP surface of the agent-bev root: the machine files on agent-bev.ai, the keyrings on bev-registry.ai and bev-x402.ai, the Registry's verification records, and the x402 payment door at /api (its receipt key, receipts and settled register under /x402/). The tools themselves are served over the Model Context Protocol at the three doors listed in /.well-known/api-catalog. No call asks for a sign-in, an account, a token or an API key (see /auth.md).",
  "contact": {
   "name": "Agent Holdings S.A.",
   "url": "https://agent-bev.ai/contact"
  },
  "termsOfService": "https://agent-bev.ai/terms"
 },
 "externalDocs": {
  "description": "auth.md — what a call needs, door by door",
  "url": "https://agent-bev.ai/auth.md"
 },
 "servers": [
  {
   "url": "https://agent-bev.ai",
   "description": "The hub (brand front and machine files)"
  }
 ],
 "security": [],
 "tags": [
  {
   "name": "discovery",
   "description": "Machine files that point an agent at the doors."
  },
  {
   "name": "keys",
   "description": "Public keyrings the signed records and receipts verify against."
  },
  {
   "name": "registry",
   "description": "The Registry's verification records (bev-registry.ai)."
  },
  {
   "name": "x402",
   "description": "The payment door (agent-bev.ai/api): x402 v2, scheme exact, on Base — USDC (EIP-3009) or Open USD (Permit2); receipts signed EdDSA (kid bev-x402-2026-10). Receipts issued by the retired proof still resolve on the Rail (bev-x402.ai)."
  }
 ],
 "paths": {
  "/facts.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getFacts",
    "summary": "The hub's facts file (surface version, operator, hosts, keys).",
    "responses": {
     "200": {
      "description": "The facts file.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/ai-catalog.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getAiCatalog",
    "summary": "The AI catalog (specVersion 1.0): the host and its doors.",
    "responses": {
     "200": {
      "description": "The AI catalog.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/ai-catalog.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getAiCatalogWellKnown",
    "summary": "The AI catalog at its well-known address (same file as /ai-catalog.json).",
    "responses": {
     "200": {
      "description": "The AI catalog.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/api-catalog": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getApiCatalog",
    "summary": "RFC 9727 API catalog: the hub, this OpenAPI description and the three MCP doors.",
    "responses": {
     "200": {
      "description": "The linkset.",
      "content": {
       "application/linkset+json": {
        "schema": {
         "type": "object",
         "required": [
          "linkset"
         ],
         "properties": {
          "linkset": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/mcp.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getMcpCard",
    "summary": "The buyers' door MCP server card (streamable-http).",
    "responses": {
     "200": {
      "description": "The MCP server card.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/mcp/server-card.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getMcpServerCard",
    "summary": "The buyers' door MCP server card (same file as /.well-known/mcp.json).",
    "responses": {
     "200": {
      "description": "The MCP server card.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/mcp/server-cards.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getMcpServerCards",
    "summary": "The MCP server cards of the three doors: buyers, sellers and the audit port.",
    "responses": {
     "200": {
      "description": "The MCP server cards.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/agent-card.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getAgentCard",
    "summary": "The hub's A2A Agent Card (the doors as supported interfaces).",
    "responses": {
     "200": {
      "description": "The Agent Card.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/agent-skills/index.json": {
   "get": {
    "tags": [
     "discovery"
    ],
    "operationId": "getAgentSkills",
    "summary": "The agent skills index (one SKILL.md per door, with its sha256 digest).",
    "responses": {
     "200": {
      "description": "The skills index.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/.well-known/jwks.json": {
   "servers": [
    {
     "url": "https://bev-registry.ai",
     "description": "The Registry keyring (record and receipt keys)"
    },
    {
     "url": "https://bev-x402.ai",
     "description": "The Rail keyring (receipt key)"
    }
   ],
   "get": {
    "tags": [
     "keys"
    ],
    "operationId": "getKeyring",
    "summary": "The public keyring (Ed25519, JWK set) the signed records and receipts verify against.",
    "responses": {
     "200": {
      "description": "The JWK set.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "keys"
         ],
         "properties": {
          "keys": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/verified/{record_id}": {
   "servers": [
    {
     "url": "https://bev-registry.ai",
     "description": "The Registry"
    }
   ],
   "get": {
    "tags": [
     "registry"
    ],
    "operationId": "getVerification",
    "summary": "A record's verification as the Registry holds it: the signed JWS, its key and the domain proof.",
    "parameters": [
     {
      "name": "record_id",
      "in": "path",
      "required": true,
      "description": "A record id: a two-letter node, \"-bev:\" and six digits (for example es-bev:000123).",
      "schema": {
       "type": "string",
       "pattern": "^[a-z]{2}-bev:\\d{6}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The record is verified.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "record_id",
          "claim_status",
          "verification"
         ],
         "properties": {
          "record_id": {
           "type": "string"
          },
          "claim_status": {
           "const": "verified"
          },
          "claimant_organisation": {
           "type": [
            "string",
            "null"
           ]
          },
          "verification": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "The record is not verified (its claim status is listed or claimed).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "const": "not_verified"
          },
          "record_id": {
           "type": "string"
          },
          "claim_status": {
           "type": "string"
          },
          "keyring": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api": {
   "get": {
    "tags": [
     "x402"
    ],
    "operationId": "getPaymentDoor",
    "summary": "The payment door: a settled payment answers with a signed receipt.",
    "description": "x402 v2, scheme exact, on Base (eip155:8453), settled through the Coinbase CDP facilitator (verify, then settle). Without a payment the door answers 402 with the offer in the body and in the PAYMENT-REQUIRED header. The offer carries two accept entries: USDC (EIP-3009 transferWithAuthorization) first, and Open USD (Permit2; the offer declares the facilitator's eip2612GasSponsoring extension, so a payer needs no gas and no standing allowance) second. The amount, the asset contracts and the pay-to addresses are stated in the offer itself. Resend with the signed payload in PAYMENT-SIGNATURE (or X-PAYMENT); the door settles the entry the payer chose and answers 200 with an EdDSA-signed receipt that resolves at /x402/receipt/{nonce}. Every answer is Cache-Control: no-store.",
    "parameters": [
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": false,
      "description": "base64 of the x402 v2 payment payload for the accept entry the payer chose (its `accepted` object names the entry).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-PAYMENT",
      "in": "header",
      "required": false,
      "description": "The same payload under the earlier header name.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Settled: the signed receipt.",
      "headers": {
       "PAYMENT-RESPONSE": {
        "description": "base64 settlement summary (success, transaction, network, payer).",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DoorReceipt"
        }
       }
      }
     },
     "402": {
      "description": "Payment required: the x402 v2 offer (also answered, with the facilitator's reply, when a presented payment does not verify).",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "base64 of the same offer.",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DoorOffer"
        }
       }
      }
     },
     "502": {
      "description": "Verified but not settled: the facilitator's reply is returned; nothing was charged.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "The rail is not configured.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/x402/jwks.json": {
   "get": {
    "tags": [
     "keys"
    ],
    "operationId": "getDoorReceiptKey",
    "summary": "The receipt key (Ed25519, JWK set, kid bev-x402-2026-10) the door's receipts verify against.",
    "responses": {
     "200": {
      "description": "The JWK set.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "keys"
         ],
         "properties": {
          "keys": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/x402/receipt/{nonce}": {
   "get": {
    "tags": [
     "x402"
    ],
    "operationId": "getDoorReceipt",
    "summary": "A signed receipt of the payment door, forever, by its nonce.",
    "parameters": [
     {
      "name": "nonce",
      "in": "path",
      "required": true,
      "description": "The receipt's 24-hex nonce (the receipt URL's last segment).",
      "schema": {
       "type": "string",
       "pattern": "^[a-f0-9]{24}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The receipt.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DoorReceipt"
        }
       }
      }
     },
     "404": {
      "description": "No receipt with this nonce.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/x402/settled.json": {
   "get": {
    "tags": [
     "x402"
    ],
    "operationId": "getDoorRegister",
    "summary": "The door's settled register: its count and its last settlement (never amounts per caller).",
    "responses": {
     "200": {
      "description": "The register.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "zone": {
           "type": "string"
          },
          "settled": {
           "type": "integer"
          },
          "last_tx": {
           "type": [
            "string",
            "null"
           ]
          },
          "last_receipt": {
           "type": [
            "string",
            "null"
           ]
          },
          "last_at": {
           "type": [
            "string",
            "null"
           ]
          },
          "as_of": {
           "type": "string"
          },
          "network": {
           "type": "string"
          },
          "asset": {
           "type": "string"
          },
          "door": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/receipt/{nonce}": {
   "servers": [
    {
     "url": "https://bev-x402.ai",
     "description": "The Rail"
    }
   ],
   "get": {
    "tags": [
     "x402"
    ],
    "operationId": "getX402Receipt",
    "summary": "A signed receipt issued by the retired proof on the Rail, forever, by its nonce.",
    "parameters": [
     {
      "name": "nonce",
      "in": "path",
      "required": true,
      "description": "The receipt's 32-hex nonce (the receipt URL's last segment).",
      "schema": {
       "type": "string",
       "pattern": "^[a-f0-9]{32}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The receipt.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Receipt"
        }
       }
      }
     },
     "400": {
      "description": "Not a 32-hex nonce.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No receipt with this nonce.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "nonce": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Offer": {
    "type": "object",
    "required": [
     "x402Version",
     "accepts"
    ],
    "properties": {
     "x402Version": {
      "const": 2
     },
     "error": {
      "type": "string"
     },
     "accepts": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "scheme": {
         "const": "exact"
        },
        "network": {
         "type": "string"
        },
        "amount": {
         "type": "string"
        },
        "maxAmountRequired": {
         "type": "string"
        },
        "asset": {
         "type": "string"
        },
        "payTo": {
         "type": "string"
        },
        "maxTimeoutSeconds": {
         "type": "integer"
        },
        "resource": {
         "type": "string",
         "format": "uri"
        },
        "description": {
         "type": "string"
        },
        "mimeType": {
         "type": "string"
        },
        "extra": {
         "type": "object"
        }
       }
      }
     },
     "resource": {
      "type": "object"
     },
     "receipts": {
      "type": "object",
      "properties": {
       "jwks": {
        "type": "string",
        "format": "uri"
       },
       "kid": {
        "type": "string"
       },
       "resolve": {
        "type": "string"
       }
      }
     },
     "operator": {
      "type": "string"
     }
    }
   },
   "Receipt": {
    "type": "object",
    "properties": {
     "iss": {
      "type": "string"
     },
     "sub": {
      "type": "string"
     },
     "jti": {
      "type": "string"
     },
     "iat": {
      "type": "integer"
     },
     "resource": {
      "type": "string"
     },
     "scheme": {
      "type": "string"
     },
     "standard": {
      "type": "string"
     },
     "network": {
      "type": "string"
     },
     "asset": {
      "type": "string"
     },
     "amount": {
      "type": "string"
     },
     "amount_usdc": {
      "type": "string"
     },
     "payTo": {
      "type": "string"
     },
     "transaction": {
      "type": [
       "string",
       "null"
      ]
     },
     "explorer": {
      "type": [
       "string",
       "null"
      ]
     },
     "settled": {
      "type": "boolean"
     },
     "facilitator": {
      "type": "string"
     },
     "receipt_url": {
      "type": "string",
      "format": "uri"
     },
     "operator": {
      "type": "string"
     },
     "jwt": {
      "type": [
       "string",
       "null"
      ],
      "description": "The receipt as an EdDSA-signed JWT (kid bev-x402-2026-10)."
     },
     "kid": {
      "type": "string"
     },
     "jwks": {
      "type": "string",
      "format": "uri"
     }
    }
   },
   "DoorOffer": {
    "type": "object",
    "required": [
     "x402Version",
     "accepts"
    ],
    "properties": {
     "x402Version": {
      "const": 2
     },
     "error": {
      "type": "string"
     },
     "resource": {
      "type": "object",
      "properties": {
       "url": {
        "type": "string",
        "format": "uri"
       },
       "description": {
        "type": "string"
       },
       "mimeType": {
        "type": "string"
       }
      }
     },
     "accepts": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2,
      "description": "Two entries: USDC (assetTransferMethod eip3009) first, Open USD (assetTransferMethod permit2) second.",
      "items": {
       "type": "object",
       "required": [
        "scheme",
        "network",
        "amount",
        "asset",
        "payTo"
       ],
       "properties": {
        "scheme": {
         "const": "exact"
        },
        "network": {
         "type": "string"
        },
        "amount": {
         "type": "string"
        },
        "asset": {
         "type": "string",
         "description": "The token contract: USDC on Base, or Open USD (OUSD) on Base."
        },
        "payTo": {
         "type": "string"
        },
        "maxTimeoutSeconds": {
         "type": "integer"
        },
        "extra": {
         "type": "object",
         "properties": {
          "assetTransferMethod": {
           "enum": [
            "eip3009",
            "permit2"
           ]
          },
          "name": {
           "type": "string"
          },
          "version": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "extensions": {
      "type": "object",
      "description": "Carries eip2612GasSponsoring."
     },
     "facilitator_response": {
      "type": "object"
     }
    }
   },
   "DoorReceipt": {
    "type": "object",
    "required": [
     "timestamp",
     "amount",
     "asset",
     "network",
     "tx_hash",
     "nonce",
     "receipt_url",
     "signature"
    ],
    "properties": {
     "confirmation": {
      "type": "string"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     },
     "amount": {
      "type": "string"
     },
     "asset": {
      "type": "string"
     },
     "asset_symbol": {
      "enum": [
       "USDC",
       "OUSD"
      ]
     },
     "network": {
      "type": "string"
     },
     "payer": {
      "type": [
       "string",
       "null"
      ]
     },
     "payTo": {
      "type": "string"
     },
     "tx_hash": {
      "type": [
       "string",
       "null"
      ],
      "description": "The Base transaction."
     },
     "settled_amount": {
      "type": "string"
     },
     "nonce": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$"
     },
     "receipt_url": {
      "type": "string",
      "format": "uri"
     },
     "issuer": {
      "type": "string"
     },
     "signature": {
      "type": "object",
      "required": [
       "alg",
       "kid",
       "value"
      ],
      "properties": {
       "alg": {
        "const": "EdDSA"
       },
       "kid": {
        "type": "string"
       },
       "canonicalization": {
        "type": "string"
       },
       "value": {
        "type": "string",
        "description": "base64url Ed25519 signature over the receipt without this field, as JSON with sorted keys and no whitespace."
       }
      }
     }
    }
   }
  }
 }
}