{
  "openapi": "3.1.0",
  "info": {
    "title": "BaseFriend Public Tipping API",
    "version": "1.2.0",
    "description": "Anonymous read-only CHEERS prelaunch data for Farcaster Mini Apps. 30 requests/IP/minute; global 600/minute; shared 60-second cache. No tip sending, spending authority or claims. Calendar UTC month totals differ from programme-relative budget periods. Optional server API keys attribute daily app activity for manual grant review; requests never award grant scores automatically. Successful keyed summary/account/sent-leaderboard/received-leaderboard requests contribute1/3/1/1 provisional activity points within the shared100-point daily read/preparation cap. Final grant scores require manual review."
  },
  "servers": [
    {
      "url": "https://basefriend.tech/api/public/tipping/v1",
      "description": "Available only after deployment and explicit activation."
    }
  ],
  "security": [
    {},
    {
      "BuilderAppKey": []
    }
  ],
  "paths": {
    "/summary": {
      "get": {
        "operationId": "getTippingSummary",
        "summary": "Programme, actual accepted tip totals, frozen day metadata and emission schedule.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Consistent cached read. Amounts may be null while pending.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryEnvelope"
                }
              }
            }
          },
          "304": {
            "description": "Matching ETag; no body.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid selectors.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Public API disabled or wrong chain/market scope.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Read-only method unsupported (framework response).",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Request limit; respect Retry-After.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Data unavailable, programme not started, refresh busy or quota reached.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "getTippingAccount",
        "summary": "FID account-wide frozen allowance and latest 20 real tips. No wallet or Crew breakdowns.",
        "parameters": [
          {
            "name": "fid",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consistent cached read. Amounts may be null while pending.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountEnvelope"
                }
              }
            }
          },
          "304": {
            "description": "Matching ETag; no body.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid selectors.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Public API disabled or wrong chain/market scope.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Read-only method unsupported (framework response).",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Request limit; respect Retry-After.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Data unavailable, programme not started, refresh busy or quota reached.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/leaderboard": {
      "get": {
        "operationId": "getTippingLeaderboard",
        "summary": "Top 50 accepted senders/receivers; equal amounts sort by numeric FID.",
        "parameters": [
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "enum": [
                "sent",
                "received"
              ],
              "default": "received"
            }
          },
          {
            "name": "period",
            "in": "query",
            "schema": {
              "enum": [
                "day",
                "month",
                "all"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consistent cached read. Amounts may be null while pending.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardEnvelope"
                }
              }
            }
          },
          "304": {
            "description": "Matching ETag; no body.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid selectors.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Public API disabled or wrong chain/market scope.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Read-only method unsupported (framework response).",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Request limit; respect Retry-After.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Data unavailable, programme not started, refresh busy or quota reached.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Response validator."
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retry."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                },
                "description": "Per-IP request ceiling per minute."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                },
                "description": "Remaining origin requests in this IP window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string"
                },
                "description": "Unix seconds at IP window reset."
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              }
            },
            "required": [
              "code"
            ]
          }
        },
        "required": [
          "apiVersion",
          "error"
        ]
      },
      "HistoryTip": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "senderFid": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "recipientFid": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "amountAtoms": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
          },
          "authorizedAt": {
            "type": "string",
            "format": "date-time"
          },
          "direction": {
            "enum": [
              "sent",
              "received"
            ]
          }
        },
        "required": [
          "id",
          "senderFid",
          "recipientFid",
          "amountAtoms",
          "authorizedAt",
          "direction"
        ]
      },
      "Account": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "symbol": {
            "const": "CHEERS"
          },
          "decimals": {
            "const": 18
          },
          "token": {
            "type": "null"
          },
          "mode": {
            "const": "prelaunch"
          },
          "funded": {
            "const": false
          },
          "claimingEnabled": {
            "const": false
          },
          "claimAfterLaunch": {
            "const": true
          },
          "fid": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "programId": {
            "type": "string",
            "format": "uuid"
          },
          "startsOn": {
            "type": "string",
            "format": "date"
          },
          "day": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "enum": [
              "active",
              "snapshot_pending",
              "identity_pending",
              "paused",
              "ended"
            ]
          },
          "allowance": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "enum": [
                  "ready",
                  "pending"
                ]
              },
              "amountAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "spentAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "remainingAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "sourceBlock": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceHash": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "finality": {
                "enum": [
                  "finalized",
                  null
                ]
              }
            },
            "required": [
              "status",
              "amountAtoms",
              "spentAtoms",
              "remainingAtoms",
              "sourceBlock",
              "sourceHash",
              "finality"
            ]
          },
          "receivedTotalAtoms": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
          },
          "totals": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "sentTodayAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "receivedTodayAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "sentMonthAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "receivedMonthAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              }
            },
            "required": [
              "sentTodayAtoms",
              "receivedTodayAtoms",
              "sentMonthAtoms",
              "receivedMonthAtoms"
            ]
          },
          "monthBasis": {
            "const": "calendar_utc"
          },
          "history": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/HistoryTip"
            }
          },
          "historyLimit": {
            "const": 20
          }
        },
        "required": [
          "symbol",
          "decimals",
          "token",
          "mode",
          "funded",
          "claimingEnabled",
          "claimAfterLaunch",
          "fid",
          "programId",
          "startsOn",
          "day",
          "status",
          "allowance",
          "receivedTotalAtoms",
          "totals",
          "monthBasis",
          "history",
          "historyLimit"
        ]
      },
      "Summary": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "symbol": {
            "const": "CHEERS"
          },
          "decimals": {
            "const": 18
          },
          "token": {
            "type": "null"
          },
          "mode": {
            "const": "prelaunch"
          },
          "funded": {
            "const": false
          },
          "claimingEnabled": {
            "const": false
          },
          "claimAfterLaunch": {
            "const": true
          },
          "chainId": {
            "const": 8453
          },
          "programId": {
            "type": "string",
            "format": "uuid"
          },
          "startsOn": {
            "type": "string",
            "format": "date"
          },
          "day": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "enum": [
              "active",
              "snapshot_pending",
              "identity_pending",
              "paused",
              "ended"
            ]
          },
          "annualBudgetAtoms": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
          },
          "currentPeriod": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 12
          },
          "scheduledDailyBudgetAtoms": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
          },
          "today": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "enum": [
                  "ready",
                  "pending"
                ]
              },
              "budgetAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "allocatedAtoms": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]*)$",
                "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
              },
              "sourceBlock": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceHash": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "finality": {
                "enum": [
                  "finalized",
                  null
                ]
              }
            },
            "required": [
              "status",
              "budgetAtoms",
              "allocatedAtoms",
              "sourceBlock",
              "sourceHash",
              "finality"
            ]
          },
          "totals": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "tips": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "amountAtoms": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "tipsToday": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "amountTodayAtoms": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "participants": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              }
            },
            "required": [
              "tips",
              "amountAtoms",
              "tipsToday",
              "amountTodayAtoms",
              "participants"
            ]
          },
          "schedule": {
            "type": "array",
            "minItems": 12,
            "maxItems": 12,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "period": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 12
                },
                "days": {
                  "type": "integer"
                },
                "budgetAtoms": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]*)$",
                  "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
                },
                "startsOn": {
                  "type": "string",
                  "format": "date"
                },
                "endsBefore": {
                  "type": "string",
                  "format": "date"
                }
              },
              "required": [
                "period",
                "days",
                "budgetAtoms",
                "startsOn",
                "endsBefore"
              ]
            }
          }
        },
        "required": [
          "symbol",
          "decimals",
          "token",
          "mode",
          "funded",
          "claimingEnabled",
          "claimAfterLaunch",
          "chainId",
          "programId",
          "startsOn",
          "day",
          "status",
          "annualBudgetAtoms",
          "currentPeriod",
          "scheduledDailyBudgetAtoms",
          "today",
          "totals",
          "schedule"
        ]
      },
      "Leaderboard": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "symbol": {
            "const": "CHEERS"
          },
          "decimals": {
            "const": 18
          },
          "token": {
            "type": "null"
          },
          "mode": {
            "const": "prelaunch"
          },
          "funded": {
            "const": false
          },
          "claimingEnabled": {
            "const": false
          },
          "claimAfterLaunch": {
            "const": true
          },
          "programId": {
            "type": "string",
            "format": "uuid"
          },
          "day": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "enum": [
              "active",
              "snapshot_pending",
              "identity_pending",
              "paused",
              "ended"
            ]
          },
          "direction": {
            "enum": [
              "sent",
              "received"
            ]
          },
          "period": {
            "enum": [
              "day",
              "month",
              "all"
            ]
          },
          "monthBasis": {
            "const": "calendar_utc"
          },
          "rows": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "rank": {
                  "type": "integer",
                  "minimum": 1
                },
                "fid": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 9007199254740991
                },
                "amountAtoms": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]*)$",
                  "description": "Exact CHEERS atoms (18 decimals); use BigInt, never Number."
                },
                "tips": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]*)$"
                }
              },
              "required": [
                "rank",
                "fid",
                "amountAtoms",
                "tips"
              ]
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          }
        },
        "required": [
          "symbol",
          "decimals",
          "token",
          "mode",
          "funded",
          "claimingEnabled",
          "claimAfterLaunch",
          "programId",
          "day",
          "status",
          "direction",
          "period",
          "monthBasis",
          "rows",
          "limit"
        ]
      },
      "AccountEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/Account"
          }
        },
        "required": [
          "apiVersion",
          "asOf",
          "expiresAt",
          "data"
        ]
      },
      "SummaryEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/Summary"
          }
        },
        "required": [
          "apiVersion",
          "asOf",
          "expiresAt",
          "data"
        ]
      },
      "LeaderboardEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/Leaderboard"
          }
        },
        "required": [
          "apiVersion",
          "asOf",
          "expiresAt",
          "data"
        ]
      }
    },
    "securitySchemes": {
      "BuilderAppKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "bfapp_<key UUID>_<random secret>",
        "description": "Optional server-only app attribution. Anonymous access remains available with identical shared limits. Never embed the key in a Mini App/browser bundle. Invalid or revoked keys return401; tracked responses are private, no-store."
      }
    },
    "headers": {
      "BuilderUsage": {
        "description": "recorded confirms saved app aggregates; anonymous and not-recorded do not attribute activity.",
        "schema": {
          "type": "string",
          "enum": [
            "recorded",
            "anonymous",
            "not-recorded"
          ]
        }
      }
    },
    "responses": {
      "InvalidAppKey": {
        "description": "Invalid or revoked optional app key. Remove Authorization for an anonymous call.",
        "headers": {
          "X-BaseFriend-Usage": {
            "$ref": "#/components/headers/BuilderUsage"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
