openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Stores (Rates) API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Stores (Rates)
  description: Stores rate information and configuration
paths:
  /api/v1/stores/{storeId}/rates:
    get:
      tags:
      - Stores (Rates)
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: currencyPair
        description: The currency pairs to fetch rates for
        example:
        - BTC_USD
        - BTC_EUR
        in: query
        style: form
        explode: true
        schema:
          type: array
          nullable: true
          items:
            type: string
        x-position: 1
      summary: Get rates
      description: Get rates on the store
      operationId: Stores_GetStoreRates
      responses:
        '200':
          description: The settings were executed and a preview was returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreRateResult'
        '400':
          description: A list of errors that occurred when previewing the settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to modify the store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/rates/configuration/{rateSource}:
    get:
      tags:
      - Stores (Rates)
      summary: Get store rate settings for the specified rate source
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/RateSource'
      description: View rate settings for the specified store and rate source (`primary` or `fallback`).
      operationId: Stores_GetStoreRateConfiguration
      responses:
        '200':
          description: specified store rate settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRateConfiguration'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The specified store or rate source was not found
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Stores (Rates)
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/RateSource'
      summary: Get store rate settings for the specified rate source
      description: Update rate settings for the specified store and rate source (`primary` or `fallback`).
      operationId: Stores_UpdateStoreRateConfiguration
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreRateConfiguration'
        required: true
        x-position: 1
      responses:
        '200':
          description: The settings were updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRateConfiguration'
        '400':
          description: A list of errors that occurred when updating the settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to modify the store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/rates/configuration/preview:
    post:
      tags:
      - Stores (Rates)
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: currencyPair
        description: The currency pairs to preview
        in: query
        style: form
        explode: true
        schema:
          type: array
          nullable: true
          items:
            type: string
        x-position: 1
      summary: Preview rate configuration results
      description: Preview rate configuration results before you set it on the store
      operationId: Stores_PreviewStoreRateConfiguration
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreRateConfiguration'
        required: true
        x-position: 1
      responses:
        '200':
          description: The settings were executed and a preview was returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoreRateResult'
        '400':
          description: A list of errors that occurred when previewing the settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to modify the store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
components:
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
    RateSource:
      name: rateSource
      in: path
      required: true
      description: The rate source to configure (`primary` or `fallback`)
      schema:
        type: string
        default: primary
        example: primary
  schemas:
    StoreRateConfiguration:
      type: object
      additionalProperties: false
      properties:
        spread:
          type: string
          description: A spread applies to the rate fetched in `%`. Must be `>= 0` or `<= 100`
        preferredSource:
          type: string
          description: When `isCustomScript` is `false`, uses this source in the default `effectiveScript`. When `isCustomScript` is `true`, this field is ignored (set to `null`). See `/misc/rate-sources` for available sources.
        isCustomScript:
          type: boolean
          description: Whether to use `preferredSource` with default script or a custom `effectiveScript`.
        effectiveScript:
          type: string
          description: When `isCustomScript` is `true`, this represent the custom script used to calculate a currency pair's exchange rate. Else, it represent the script generated by the default rules and `preferredSource`.
    StoreRateResult:
      type: object
      additionalProperties: false
      properties:
        currencyPair:
          type: string
          example: BTC_USD
          description: Currency pair in the format of `BTC_USD`
        errors:
          type: array
          nullable: true
          items:
            type: string
          description: Errors relating to this currency pair fetching based on your config
        rate:
          type: string
          format: decimal
          example: '64392.23'
          description: the rate fetched based on the currency pair
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            nullable: false
            description: The json path of the property which failed validation
          message:
            type: string
            nullable: false
            description: User friendly error message about the validation
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/