{
  "openapi": "3.0.3",
  "info": {
    "title": "Bull RFQ API",
    "version": "v1",
    "description": "Private OTC block trades for ERC-20 tokens on Robinhood Chain. Settlement is atomic in the BullEscrow contract; this API only prepares and tracks deals. Auth: sign every request with your wallet (EIP-191). See /llms.txt."
  },
  "servers": [
    {
      "url": "https://www.bull.family/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "walletSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-bull-signature",
        "description": "Also send x-bull-address and x-bull-timestamp (ms). Signed text: 'Bull API\\n{METHOD} {path}\\n{timestamp}\\n{sha256hex(body)}' where path is the full URL path (e.g. /api/v1/rfqs) and body is the raw request body ('' for GET). Timestamp must be within 5 minutes."
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "summary": "API info",
        "description": "Chain, escrow address, fee tiers, minimum RFQ size.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        }
      }
    },
    "/rfqs": {
      "get": {
        "summary": "List open RFQs",
        "description": "Public. Buyers who want to buy a token in size. Optional ?ca= filter.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        }
      },
      "post": {
        "summary": "Create an RFQ (buyer)",
        "description": "Post a request for quotes. The signing wallet must hold the funds.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "symbol": {
                    "type": "string"
                  },
                  "sizeUsd": {
                    "type": "number"
                  },
                  "windowMin": {
                    "type": "integer",
                    "enum": [
                      15,
                      30,
                      60,
                      360,
                      1440
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/rfqs/{id}": {
      "get": {
        "summary": "Get an RFQ",
        "description": "Public.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/rfqs/{id}/quotes": {
      "post": {
        "summary": "Send a sealed quote (seller)",
        "description": "Only the RFQ buyer can read it. Fully unlocked tokens only.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokens": {
                    "type": "string"
                  },
                  "price": {
                    "type": "string"
                  },
                  "payout": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "get": {
        "summary": "List quotes on your RFQ (buyer)",
        "description": "Buyer of the RFQ only.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}": {
      "get": {
        "summary": "Quote and deal status",
        "description": "Buyer or seller of the quote.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/accept": {
      "post": {
        "summary": "Accept a quote (buyer)",
        "description": "Returns the createDeal transaction (to, data, value) with Bull's signed fee quote. Sign and send it from your buyer wallet. Answers 409 awaiting_seller_consent until the seller signed the deal terms (GET/POST /quotes/{id}/consent).",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payAsset": {
                    "type": "string",
                    "enum": [
                      "base",
                      "alt"
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/deal": {
      "post": {
        "summary": "Attach the onchain deal (buyer)",
        "description": "Send the dealId from the DealCreated event. Returns the payment steps (approve if needed, fundPayment).",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dealId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/permit": {
      "get": {
        "summary": "Deposit instructions (seller)",
        "description": "Typed data to sign for a gasless deposit: `permit` (EIP-2612) and `fund` (the escrow's Fund message, EIP-712), plus direct approve/fundTokens steps. Available once the buyer has paid.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/deposit": {
      "post": {
        "summary": "Submit signed permit (seller)",
        "description": "Bull's relayer pays gas and deposits; the swap settles in that transaction.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "permitDeadline": {
                    "type": "string"
                  },
                  "v": {
                    "type": "integer"
                  },
                  "r": {
                    "type": "string"
                  },
                  "s": {
                    "type": "string"
                  },
                  "fundSig": {
                    "type": "string",
                    "description": "Signature over the `fund` typed data from GET /quotes/{id}/permit"
                  }
                },
                "required": [
                  "permitDeadline",
                  "v",
                  "r",
                  "s",
                  "fundSig"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/reject": {
      "post": {
        "summary": "Reject a quote (buyer)",
        "description": "",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/deals/{id}": {
      "get": {
        "summary": "Onchain deal state",
        "description": "Public. Chain is the source of truth.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/counter": {
      "post": {
        "summary": "Counter a pending quote (buyer)",
        "description": "Propose another total price (ETH) and optionally another token amount.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "price": {
                    "type": "string"
                  },
                  "tokens": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{id}/revise": {
      "post": {
        "summary": "Revise your pending quote (seller)",
        "description": "Change price and/or tokens, for example to meet a counter.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "price": {
                    "type": "string"
                  },
                  "tokens": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Public stats: settled deals, volume, recent deals",
        "description": "",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        }
      }
    },
    "/receipts/{id}": {
      "get": {
        "summary": "Signed receipt for a settled deal",
        "description": "Facts from the escrow contract, signed by Bull's fee signer.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/{id}/consent": {
      "get": {
        "summary": "Deal terms to sign (seller)",
        "description": "The exact deal terms as EIP-712 typed data, once the buyer asked to open the escrow. The escrow contract only opens the deal with this signature.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "summary": "Submit the signed deal terms (seller)",
        "description": "After this the buyer can call POST /quotes/{id}/accept again to get the createDeal transaction.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "Error: {error:{code,message}}"
          }
        },
        "security": [
          {
            "walletSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "signature": {
                    "type": "string"
                  }
                },
                "required": [
                  "signature"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}
