{
  "openapi": "3.1.0",
  "info": {
    "title": "BaseFriend public market builder API",
    "version": "1.2.0",
    "description": "Creator/club markets, wallet positions and unsigned actions. Shares30requests/IP/min with public tipping. Indexed views may lag; all payment atoms and key amounts are exact strings. No signing or broadcasting. Optional server API keys attribute daily app activity for manual grant review; requests never award grant scores automatically. Classified successful app requests earn provisional activity points (100/day); matching finalized actions earn separate points, capped at 500 total/day. Final grant scores remain manual."
  },
  "servers": [
    {
      "url": "https://basefriend.tech/api/public/basefriend/v1"
    }
  ],
  "paths": {
    "/config": {
      "get": {
        "operationId": "config",
        "summary": "Discover the reviewed contract, ABI and current payment asset",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "chainId": {
                          "const": 8453
                        },
                        "marketContract": {
                          "type": "string",
                          "pattern": "^0x[0-9a-fA-F]{40}$"
                        },
                        "settlement": {
                          "$ref": "#/components/schemas/Settlement"
                        },
                        "keyStandard": {
                          "const": "ERC1155"
                        },
                        "keyDecimals": {
                          "const": 0
                        },
                        "tradingEnabled": {
                          "type": "boolean"
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "abi": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "requestsPerMinute": {
                          "const": 30
                        },
                        "cacheSeconds": {
                          "const": 60
                        },
                        "tippingBasePath": {
                          "type": "string"
                        },
                        "grantsPath": {
                          "type": "string"
                        },
                        "activityPolicy": {
                          "$ref": "#/components/schemas/ActivityPolicy"
                        },
                        "actionConfirmationPath": {
                          "const": "/api/public/basefriend/v1/confirm"
                        }
                      },
                      "required": [
                        "chainId",
                        "marketContract",
                        "settlement",
                        "keyStandard",
                        "keyDecimals",
                        "tradingEnabled",
                        "actions",
                        "abi",
                        "requestsPerMinute",
                        "cacheSeconds",
                        "tippingBasePath",
                        "grantsPath",
                        "activityPolicy",
                        "actionConfirmationPath"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/markets": {
      "get": {
        "operationId": "markets",
        "summary": "List/search active creator and club markets",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "creator",
                "channel"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Market"
                          },
                          "maxItems": 50
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "settlement": {
                          "$ref": "#/components/schemas/Settlement"
                        },
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        }
                      },
                      "required": [
                        "items",
                        "nextCursor",
                        "settlement",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/market": {
      "get": {
        "operationId": "market",
        "summary": "Read one market",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "market": {
                          "$ref": "#/components/schemas/Market"
                        },
                        "settlement": {
                          "$ref": "#/components/schemas/Settlement"
                        },
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        }
                      },
                      "required": [
                        "market",
                        "settlement",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/wallet": {
      "get": {
        "operationId": "wallet",
        "summary": "Read public indexed holdings, stakes and reward estimates",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Position"
                          },
                          "maxItems": 50
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "settlement": {
                          "$ref": "#/components/schemas/Settlement"
                        },
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        }
                      },
                      "required": [
                        "items",
                        "nextCursor",
                        "settlement",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/quote": {
      "get": {
        "operationId": "quote",
        "summary": "Get a short-lived wallet-specific quote including Genesis debt",
        "parameters": [
          {
            "name": "entityId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          },
          {
            "name": "side",
            "in": "query",
            "required": true,
            "schema": {
              "enum": [
                "buy",
                "sell"
              ]
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,5}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Quote"
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          }
        }
      }
    },
    "/prepare": {
      "post": {
        "operationId": "prepareUnsignedAction",
        "summary": "Prepare only; caller must verify, simulate, sign and broadcast through their own wallet",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrepareInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Cache up to60seconds for indexed views; quotes/preparation are no-store and expire within10seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiVersion": {
                      "const": "1"
                    },
                    "asOf": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Prepared"
                    }
                  },
                  "required": [
                    "apiVersion",
                    "asOf",
                    "expiresAt",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidAppKey"
          },
          "403": {
            "description": "Genesis claimant approval or an existing wallet-bound authorization is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          }
        }
      }
    },
    "/confirm": {
      "post": {
        "operationId": "confirmBuilderAction",
        "summary": "Verify an app-bound direct market transaction after finality; does not broadcast",
        "security": [
          {
            "BuilderAppKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent verified action evidence; qualifying points remain subject to daily caps and manual review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfirmedAction"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "400": {
            "description": "Invalid input, keys locked or owner required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "404": {
            "description": "Disabled or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "409": {
            "description": "Price/asset moved or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "413": {
            "description": "Body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "429": {
            "description": "Shared30/IP/min limit; respect Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "503": {
            "description": "Provider or global refresh capacity unavailable; back off",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "401": {
            "description": "Valid app key required; Genesis identity authorization is validated separately.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "403": {
            "description": "Valid app key required; Genesis identity authorization is validated separately.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            }
          },
          "202": {
            "description": "Transaction not yet visible or finalized. Retry after at least60seconds; never submit the transaction again.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "const": "60"
                }
              },
              "X-BaseFriend-Usage": {
                "$ref": "#/components/headers/BuilderUsage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PendingAction"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              }
            },
            "required": [
              "code"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "apiVersion",
          "error"
        ],
        "additionalProperties": false
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "data": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$"
          },
          "value": {
            "const": "0x0"
          }
        },
        "required": [
          "to",
          "data",
          "value"
        ],
        "additionalProperties": false
      },
      "Settlement": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "symbol": {
            "enum": [
              "KEY",
              "DEGEN"
            ]
          },
          "decimals": {
            "const": 18
          },
          "identity": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{64}$"
          },
          "inputAtoms": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "outputAtoms": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "active": {
            "type": "boolean"
          },
          "assetBound": {
            "type": "boolean"
          },
          "blockNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "blockHash": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "asset",
          "symbol",
          "decimals",
          "identity",
          "inputAtoms",
          "outputAtoms",
          "active",
          "assetBound",
          "blockNumber",
          "blockHash"
        ],
        "additionalProperties": false
      },
      "Source": {
        "type": "object",
        "properties": {
          "type": {
            "const": "confirmed_index"
          },
          "blockNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "indexedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "mayLag": {
            "const": true
          }
        },
        "required": [
          "type",
          "blockNumber",
          "indexedAt",
          "mayLag"
        ],
        "additionalProperties": false
      },
      "Market": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "enum": [
              "creator",
              "channel"
            ]
          },
          "name": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "avatarUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "fid": {
            "type": [
              "string",
              "null"
            ]
          },
          "channelId": {
            "type": [
              "string",
              "null"
            ]
          },
          "claimed": {
            "type": "boolean"
          },
          "genesisClaimed": {
            "type": "boolean"
          },
          "owner": {
            "type": [
              "string",
              "null"
            ]
          },
          "tokenId": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "decimals": {
            "const": 0
          },
          "supply": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "holders": {
            "type": [
              "integer",
              "null"
            ]
          },
          "stakers": {
            "type": [
              "integer",
              "null"
            ]
          },
          "indicativeBuyPriceAtoms": {
            "type": [
              "string",
              "null"
            ]
          },
          "priceAsOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "indicative": {
            "const": true
          }
        },
        "required": [
          "id",
          "type",
          "name",
          "username",
          "avatarUrl",
          "fid",
          "channelId",
          "claimed",
          "genesisClaimed",
          "owner",
          "tokenId",
          "decimals",
          "supply",
          "holders",
          "stakers",
          "indicativeBuyPriceAtoms",
          "priceAsOf",
          "indicative"
        ],
        "additionalProperties": true
      },
      "Position": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Market"
          },
          {
            "type": "object",
            "properties": {
              "liquidKeys": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$"
              },
              "stakedKeys": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$"
              },
              "unlockedKeys": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$"
              },
              "nextUnlockAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "indexedClaimableRewardAtoms": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$"
              }
            },
            "required": [
              "liquidKeys",
              "stakedKeys",
              "unlockedKeys",
              "nextUnlockAt",
              "indexedClaimableRewardAtoms"
            ],
            "additionalProperties": true
          }
        ]
      },
      "Quote": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "string",
            "format": "uuid"
          },
          "wallet": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "amount": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,5}$"
          },
          "side": {
            "enum": [
              "buy",
              "sell"
            ]
          },
          "curveAmount": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "reserveAmount": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "royalty": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "genesisDebt": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "genesisDebtWithheld": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "genesisDebtPayment": {
            "type": "string",
            "pattern": "^[0-9]{1,78}$"
          },
          "paymentAsset": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "paymentSymbol": {
            "enum": [
              "KEY",
              "DEGEN"
            ]
          },
          "settlementIdentity": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{64}$"
          },
          "settlement": {
            "$ref": "#/components/schemas/Settlement"
          },
          "expiresAt": {
            "type": "integer"
          },
          "indicative": {
            "const": false
          },
          "source": {
            "const": "BASEFRIEND_CONTRACT"
          }
        },
        "required": [
          "entityId",
          "wallet",
          "amount",
          "side",
          "curveAmount",
          "reserveAmount",
          "royalty",
          "genesisDebt",
          "genesisDebtWithheld",
          "genesisDebtPayment",
          "paymentAsset",
          "paymentSymbol",
          "settlementIdentity",
          "settlement",
          "expiresAt",
          "indicative",
          "source"
        ],
        "additionalProperties": true
      },
      "PrepareInput": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "action": {
                "enum": [
                  "buy",
                  "sell"
                ]
              },
              "wallet": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "entityId": {
                "type": "string",
                "format": "uuid"
              },
              "amount": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,5}$"
              },
              "referenceAmount": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$"
              },
              "slippageBps": {
                "type": "integer",
                "minimum": 0,
                "maximum": 500
              },
              "settlementIdentity": {
                "type": "string",
                "pattern": "^0x[0-9a-f]{64}$"
              },
              "maxGenesisDebtPayment": {
                "type": "string",
                "pattern": "^[0-9]{1,78}$",
                "default": "0"
              }
            },
            "required": [
              "action",
              "wallet",
              "entityId",
              "amount",
              "referenceAmount",
              "slippageBps",
              "settlementIdentity"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "action": {
                "enum": [
                  "stake",
                  "unstake"
                ]
              },
              "wallet": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "entityId": {
                "type": "string",
                "format": "uuid"
              },
              "amount": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,5}$"
              }
            },
            "required": [
              "action",
              "wallet",
              "entityId",
              "amount"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "action": {
                "const": "claim_rewards"
              },
              "wallet": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "entityIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "minItems": 1,
                "maxItems": 20
              },
              "settlementIdentity": {
                "type": "string",
                "pattern": "^0x[0-9a-f]{64}$"
              }
            },
            "required": [
              "action",
              "wallet",
              "entityIds",
              "settlementIdentity"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "action": {
                "const": "claim_creator_fees"
              },
              "wallet": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "entityId": {
                "type": "string",
                "format": "uuid"
              },
              "settlementIdentity": {
                "type": "string",
                "pattern": "^0x[0-9a-f]{64}$"
              }
            },
            "required": [
              "action",
              "wallet",
              "entityId",
              "settlementIdentity"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "action": {
                "const": "claim_genesis"
              },
              "wallet": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "entityId": {
                "type": "string",
                "format": "uuid"
              },
              "authorization": {
                "type": "object",
                "properties": {
                  "deadline": {
                    "type": "string",
                    "pattern": "^[1-9][0-9]{9,11}$"
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{130}$"
                  }
                },
                "required": [
                  "deadline",
                  "signature"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "action",
              "wallet",
              "entityId"
            ],
            "additionalProperties": false
          }
        ]
      },
      "Prepared": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "to": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "data": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$"
          },
          "value": {
            "const": "0x0"
          },
          "chainId": {
            "const": 8453
          },
          "action": {
            "enum": [
              "buy",
              "sell",
              "stake",
              "unstake",
              "claim_rewards",
              "claim_creator_fees",
              "claim_genesis"
            ]
          },
          "unsigned": {
            "const": true
          },
          "requiresSimulation": {
            "const": true
          },
          "approval": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Transaction"
              },
              {
                "type": "null"
              }
            ]
          },
          "quote": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "string",
                    "pattern": "^[1-9][0-9]{0,5}$"
                  },
                  "side": {
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "curveAmount": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "reserveAmount": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "royalty": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "genesisDebt": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "genesisDebtWithheld": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "genesisDebtPayment": {
                    "type": "string",
                    "pattern": "^[0-9]{1,78}$"
                  },
                  "paymentAsset": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "paymentSymbol": {
                    "enum": [
                      "KEY",
                      "DEGEN"
                    ]
                  },
                  "settlementIdentity": {
                    "type": "string",
                    "pattern": "^0x[0-9a-f]{64}$"
                  },
                  "settlement": {
                    "$ref": "#/components/schemas/Settlement"
                  },
                  "expiresAt": {
                    "type": "integer"
                  },
                  "indicative": {
                    "const": false
                  },
                  "source": {
                    "const": "BASEFRIEND_CONTRACT"
                  }
                },
                "required": [
                  "amount",
                  "side",
                  "curveAmount",
                  "reserveAmount",
                  "royalty",
                  "genesisDebt",
                  "genesisDebtWithheld",
                  "genesisDebtPayment",
                  "paymentAsset",
                  "paymentSymbol",
                  "settlementIdentity",
                  "settlement",
                  "expiresAt",
                  "indicative",
                  "source"
                ]
              }
            ]
          },
          "settlement": {
            "$ref": "#/components/schemas/Settlement"
          },
          "activity": {
            "$ref": "#/components/schemas/ActionIntent"
          }
        },
        "required": [
          "from",
          "to",
          "data",
          "value",
          "chainId",
          "action",
          "unsigned",
          "requiresSimulation"
        ],
        "additionalProperties": true
      },
      "ActivityPolicy": {
        "type": "object",
        "properties": {
          "version": {
            "const": "builder-activity-20261118-v1"
          },
          "requestDailyCap": {
            "const": 100
          },
          "totalDailyCap": {
            "const": 500
          },
          "timezone": {
            "const": "UTC"
          },
          "manualReviewRequired": {
            "const": true
          },
          "requestPoints": {
            "type": "object",
            "properties": {
              "legacy": {
                "const": 0
              },
              "unknown": {
                "const": 0
              },
              "config": {
                "const": 0
              },
              "markets": {
                "const": 1
              },
              "creators": {
                "const": 1
              },
              "clubs": {
                "const": 1
              },
              "search": {
                "const": 1
              },
              "market": {
                "const": 2
              },
              "wallet": {
                "const": 3
              },
              "quote_buy": {
                "const": 2
              },
              "quote_sell": {
                "const": 1
              },
              "prepare_buy": {
                "const": 2
              },
              "prepare_sell": {
                "const": 0
              },
              "prepare_stake": {
                "const": 2
              },
              "prepare_unstake": {
                "const": 0
              },
              "prepare_claim_rewards": {
                "const": 0
              },
              "prepare_claim_creator_fees": {
                "const": 0
              },
              "prepare_claim_genesis": {
                "const": 0
              },
              "summary": {
                "const": 1
              },
              "account": {
                "const": 3
              },
              "leaderboard_sent": {
                "const": 1
              },
              "leaderboard_received": {
                "const": 1
              },
              "confirm": {
                "const": 0
              }
            },
            "required": [
              "legacy",
              "unknown",
              "config",
              "markets",
              "creators",
              "clubs",
              "search",
              "market",
              "wallet",
              "quote_buy",
              "quote_sell",
              "prepare_buy",
              "prepare_sell",
              "prepare_stake",
              "prepare_unstake",
              "prepare_claim_rewards",
              "prepare_claim_creator_fees",
              "prepare_claim_genesis",
              "summary",
              "account",
              "leaderboard_sent",
              "leaderboard_received",
              "confirm"
            ],
            "additionalProperties": false
          },
          "actionPoints": {
            "type": "object",
            "properties": {
              "buy": {
                "const": 25
              },
              "sell": {
                "const": 3
              },
              "stake": {
                "const": 20
              },
              "unstake": {
                "const": 2
              },
              "claim_rewards": {
                "const": 5
              },
              "claim_creator_fees": {
                "const": 8
              },
              "claim_genesis": {
                "const": 100
              }
            },
            "required": [
              "buy",
              "sell",
              "stake",
              "unstake",
              "claim_rewards",
              "claim_creator_fees",
              "claim_genesis"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "version",
          "requestDailyCap",
          "totalDailyCap",
          "timezone",
          "manualReviewRequired",
          "requestPoints",
          "actionPoints"
        ],
        "additionalProperties": false
      },
      "ActionIntent": {
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "format": "uuid"
          },
          "policy": {
            "const": "builder-activity-20261118-v1"
          },
          "executeBefore": {
            "type": "string",
            "format": "date-time"
          },
          "reportBefore": {
            "type": "string",
            "format": "date-time"
          },
          "confirmationPath": {
            "const": "/api/public/basefriend/v1/confirm"
          },
          "requiredFinality": {
            "const": "finalized"
          },
          "manualReviewRequired": {
            "const": true
          }
        },
        "required": [
          "intentId",
          "policy",
          "executeBefore",
          "reportBefore",
          "confirmationPath",
          "requiredFinality",
          "manualReviewRequired"
        ],
        "additionalProperties": false
      },
      "ConfirmInput": {
        "type": "object",
        "properties": {
          "intentId": {
            "type": "string",
            "format": "uuid"
          },
          "txHash": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{64}$"
          }
        },
        "required": [
          "intentId",
          "txHash"
        ],
        "additionalProperties": false
      },
      "ConfirmedAction": {
        "type": "object",
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "const": "confirmed"
              },
              "txHash": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{64}$"
              },
              "action": {
                "enum": [
                  "buy",
                  "sell",
                  "stake",
                  "unstake",
                  "claim_rewards",
                  "claim_creator_fees",
                  "claim_genesis"
                ]
              },
              "day": {
                "type": "string",
                "format": "date"
              },
              "qualifyingPoints": {
                "enum": [
                  0,
                  2,
                  3,
                  5,
                  8,
                  20,
                  25,
                  100
                ]
              },
              "dailyCapsApply": {
                "const": true
              },
              "manualReviewRequired": {
                "const": true
              }
            },
            "required": [
              "status",
              "txHash",
              "action",
              "day",
              "qualifyingPoints",
              "dailyCapsApply",
              "manualReviewRequired"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "apiVersion",
          "data"
        ],
        "additionalProperties": false
      },
      "PendingAction": {
        "type": "object",
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "const": "pending"
              },
              "qualifyingPoints": {
                "const": 0
              },
              "retryAfterSeconds": {
                "const": 60
              },
              "requiredFinality": {
                "const": "finalized"
              }
            },
            "required": [
              "status",
              "qualifyingPoints",
              "retryAfterSeconds",
              "requiredFinality"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "apiVersion",
          "data"
        ],
        "additionalProperties": false
      }
    },
    "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"
            }
          }
        }
      }
    }
  },
  "security": [
    {},
    {
      "BuilderAppKey": []
    }
  ]
}
