{
  "openapi": "3.1.0",
  "info": {
    "title": "MoneyTools Spend Controls",
    "version": "1.0.0",
    "description": "Human Approval Relay and Spend Ledger for AI agents that pay with x402/USDC. Non-custodial. Run by MoneyTools (moneytools.dev). Non-custodial: approvals only record a human decision and ledgers only read receipts and public chain data; we never receive, hold, move or sign user funds or keys. Paid calls go to the MoneyTools team wallet via x402 (USDC on Base). Failed calls are not charged. Not financial, accounting or tax advice."
  },
  "servers": [
    {
      "url": "https://approve.moneytools.dev"
    },
    {
      "url": "https://ledger.moneytools.dev"
    }
  ],
  "paths": {
    "/v1/approvals": {
      "post": {
        "operationId": "approval_request",
        "summary": "Create a human approval request",
        "description": "Human approval request for an AI agent: creates an approval link (and optional signed webhook), records the human's approve/deny, returns a verifiable proof. Non-custodial. $0.003 via x402 (HTTP 402 + PAYMENT-REQUIRED) or X-API-Key.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.003000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "What the agent wants to do, e.g. 'Pay api.example.com 0.50 USDC for a report'"
                  },
                  "amountUsd": {
                    "type": "number",
                    "description": "Amount in USD the human approves (upper bound)"
                  },
                  "payTo": {
                    "type": "string",
                    "description": "0x recipient the agent will pay"
                  },
                  "host": {
                    "type": "string",
                    "description": "Seller hostname or URL"
                  },
                  "network": {
                    "type": "string",
                    "description": "e.g. eip155:8453"
                  },
                  "details": {
                    "type": "string",
                    "description": "Extra context for the human (max 1000 chars)"
                  },
                  "ttlMinutes": {
                    "type": "number",
                    "description": "5-1440, default 30"
                  },
                  "notify": {
                    "type": "object",
                    "description": "{ webhook?: https URL (signed POST), email?: address (limited availability), telegramChatId?: string (not enabled yet) }"
                  }
                },
                "required": [
                  "title"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input (not charged)"
          },
          "402": {
            "description": "Payment Required (x402 v2)"
          }
        }
      }
    },
    "/v1/approvals/{id}": {
      "get": {
        "operationId": "approval_status",
        "summary": "Approval status (free, Bearer agentToken)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "status"
          },
          "404": {
            "description": "not found / wrong token"
          }
        }
      }
    },
    "/v1/approvals/{id}/consume": {
      "post": {
        "operationId": "approval_consume",
        "summary": "Mark an approved request used (free, single-use)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "consumed"
          },
          "409": {
            "description": "not approved / already used / mismatch"
          }
        }
      }
    },
    "/v1/approvals/{id}/cancel": {
      "post": {
        "operationId": "approval_cancel",
        "summary": "Cancel a pending request (free)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "cancelled"
          }
        }
      }
    },
    "/v1/approvals/verify": {
      "get": {
        "operationId": "approval_verify",
        "summary": "Verify an approval proof (free)",
        "parameters": [
          {
            "name": "proof",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "valid or not"
          }
        }
      }
    },
    "/v1/ledger": {
      "get": {
        "operationId": "ledger_gateway",
        "summary": "Spend ledger from Pay Gateway receipts (free with X-API-Key)",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ledger JSON or CSV"
          },
          "401": {
            "description": "X-API-Key required"
          }
        }
      }
    },
    "/v1/ledger/wallet": {
      "post": {
        "operationId": "ledger_wallet_start",
        "summary": "Start a spend ledger for any Base wallet (one UTC month)",
        "description": "Spend ledger for any Base wallet over the last 30 days (or the current UTC month): outgoing USDC by recipient and day, CSV export, optional currency conversion. Read-only. $0.05 via x402 (HTTP 402 + PAYMENT-REQUIRED) or X-API-Key.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "0x Base wallet whose outgoing USDC to report"
                  },
                  "days": {
                    "type": "number",
                    "description": "last N days, 1-31 (default 30)"
                  },
                  "month": {
                    "type": "string",
                    "description": "YYYY-MM (UTC); only months that started within the last 31 days"
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO 4217 code, default USD"
                  },
                  "labels": {
                    "type": "object",
                    "description": "{\"0xrecipient\":\"name\"} to label suppliers"
                  }
                },
                "required": [
                  "address"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input (not charged)"
          },
          "402": {
            "description": "Payment Required (x402 v2)"
          }
        }
      }
    },
    "/v1/ledger/report/{id}": {
      "get": {
        "operationId": "ledger_wallet_report",
        "summary": "Read / advance a wallet ledger report (free with reportToken)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "progress or report"
          }
        }
      }
    }
  }
}