{
  "openapi": "3.1.0",
  "info": {
    "title": "Circle Agent Readiness API",
    "version": "0.1.0",
    "description": "Validate autonomous finance agent manifests before they are allowed to transact.",
    "x-guidance": "Use this API before launching or listing an autonomous finance agent. Call POST /inspect/circle-agent-readiness with wallet, spending policy, delegation, x402, marketplace, and MCP readiness fields."
  },
  "servers": [
    {
      "url": "https://circle-agent-readiness-api.vercel.app"
    }
  ],
  "components": {
    "schemas": {
      "ReadinessFinding": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "flag",
          "recommendation"
        ],
        "properties": {
          "flag": {
            "type": "string"
          },
          "recommendation": {
            "type": "string"
          }
        }
      },
      "ReadinessManifest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "wallet",
          "spendingPolicy",
          "delegations",
          "x402",
          "marketplace",
          "mcp"
        ],
        "properties": {
          "wallet": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "configured",
              "supportedNetworks",
              "supportedAssets"
            ],
            "properties": {
              "configured": {
                "type": "boolean"
              },
              "supportedNetworks": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "supportedAssets": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "spendingPolicy": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "perTransactionLimitUsd",
              "dailyLimitUsd",
              "recipientAllowlistEnabled",
              "contractAllowlistEnabled"
            ],
            "properties": {
              "perTransactionLimitUsd": {
                "type": "number",
                "exclusiveMinimum": 0
              },
              "dailyLimitUsd": {
                "type": "number",
                "exclusiveMinimum": 0
              },
              "recipientAllowlistEnabled": {
                "type": "boolean"
              },
              "contractAllowlistEnabled": {
                "type": "boolean"
              }
            }
          },
          "delegations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "name",
                "canTransfer",
                "canCallContracts",
                "maxSpendUsd"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "canTransfer": {
                  "type": "boolean"
                },
                "canCallContracts": {
                  "type": "boolean"
                },
                "maxSpendUsd": {
                  "type": "number",
                  "exclusiveMinimum": 0
                }
              }
            }
          },
          "x402": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "buyerCompatible"
            ],
            "properties": {
              "buyerCompatible": {
                "type": "boolean"
              }
            }
          },
          "marketplace": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "listingMetadataReady"
            ],
            "properties": {
              "listingMetadataReady": {
                "type": "boolean"
              }
            }
          },
          "mcp": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "serverExposed",
              "toolsDeclared"
            ],
            "properties": {
              "serverExposed": {
                "type": "boolean"
              },
              "toolsDeclared": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "ReadinessChecks": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "walletConfigured",
          "usdcSupported",
          "supportedNetworks",
          "spendingLimits",
          "policyRules",
          "delegatedPermissionsBounded",
          "x402Compatible",
          "marketplaceReady",
          "mcpCompatible"
        ],
        "properties": {
          "walletConfigured": {
            "type": "boolean"
          },
          "usdcSupported": {
            "type": "boolean"
          },
          "supportedNetworks": {
            "type": "boolean"
          },
          "spendingLimits": {
            "type": "boolean"
          },
          "policyRules": {
            "type": "boolean"
          },
          "delegatedPermissionsBounded": {
            "type": "boolean"
          },
          "x402Compatible": {
            "type": "boolean"
          },
          "marketplaceReady": {
            "type": "boolean"
          },
          "mcpCompatible": {
            "type": "boolean"
          }
        }
      },
      "ReadinessResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scoringModelVersion",
          "readinessScore",
          "status",
          "riskLevel",
          "checks",
          "findings",
          "riskFlags",
          "recommendations"
        ],
        "properties": {
          "scoringModelVersion": {
            "type": "string",
            "enum": [
              "1.0"
            ]
          },
          "readinessScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "status": {
            "type": "string",
            "enum": [
              "agent_ready",
              "ready_with_warnings",
              "needs_attention",
              "not_ready"
            ]
          },
          "riskLevel": {
            "type": "string",
            "enum": [
              "low",
              "moderate",
              "high",
              "critical"
            ]
          },
          "checks": {
            "$ref": "#/components/schemas/ReadinessChecks"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReadinessFinding"
            }
          },
          "riskFlags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "recommendations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Return service health.",
        "responses": {
          "200": {
            "description": "Service is healthy."
          }
        }
      }
    },
    "/x402/routes": {
      "get": {
        "operationId": "listX402Routes",
        "summary": "List paid route metadata.",
        "responses": {
          "200": {
            "description": "Paid route catalog."
          }
        }
      }
    },
    "/inspect/circle-agent-readiness": {
      "post": {
        "operationId": "inspectCircleAgentReadiness",
        "summary": "Inspect an autonomous finance agent manifest and return readiness score, risk flags, and policy recommendations.",
        "description": "Inspect an autonomous finance agent manifest and return readiness score, risk flags, and policy recommendations. Price suggestion: 0.01 USDC per call.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadinessManifest"
              },
              "example": {
                "wallet": {
                  "configured": true,
                  "supportedNetworks": [
                    "eip155:8453"
                  ],
                  "supportedAssets": [
                    "USDC"
                  ]
                },
                "spendingPolicy": {
                  "perTransactionLimitUsd": 25,
                  "dailyLimitUsd": 100,
                  "recipientAllowlistEnabled": true,
                  "contractAllowlistEnabled": true
                },
                "delegations": [
                  {
                    "name": "payment_worker",
                    "canTransfer": true,
                    "canCallContracts": false,
                    "maxSpendUsd": 25
                  }
                ],
                "x402": {
                  "buyerCompatible": true
                },
                "marketplace": {
                  "listingMetadataReady": true
                },
                "mcp": {
                  "serverExposed": true,
                  "toolsDeclared": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic readiness report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required when x402 payment mode is enabled."
          }
        }
      }
    }
  }
}