> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Rate-Locked Quote

> Create a locked exchange rate quote. The quote is valid for the specified duration and can be used once to create a transfer.

Use this endpoint to lock an exchange rate before creating a transfer. Quotes give the customer a deterministic source-to-destination conversion rate that's valid for a fixed window (30, 60, or 300 seconds). The quote captures the source amount, destination amount, exchange rate, and full fee breakdown (integrator + platform) at the moment of issuance. A quote can be redeemed exactly once by passing its ID when calling [Create Transfer](/api-reference/transfer/post).

<Info>
  Quotes are most useful for **trading** and **cross-border payouts** where the customer needs to see the exact rate they'll receive before committing the transfer. For floating-rate transfers (e.g. payroll, treasury rebalancing), skip the quote and call `/v2/transfer` directly.
</Info>


## OpenAPI

````yaml openapi/spherepay.yaml POST /v2/quote
openapi: 3.0.0
info:
  title: ''
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.spherepay.co
    description: Production
security:
  - bearer: []
tags: []
paths:
  /v2/quote:
    post:
      summary: Create a Quote
      description: >-
        Create a locked exchange rate quote. The quote is valid for the
        specified duration and can be used once to create a transfer.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuoteRequestDto'
            example:
              amount: '100.00'
              customerId: customer_3faa484998f44cfead9668608b9ee1f5
              source:
                currency: usdc
                network: polygon
              destination:
                currency: brl
                network: pix
              quoteDurationSeconds: 60
              integratorBpsFeeRate: '20'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuoteResponseDto'
              example:
                id: quote_d243ab2b1de4447d8a046d87fefe58cf
                type: off_ramp
                customerId: customer_3faa484998f44cfead9668608b9ee1f5
                fees:
                  integratorFee:
                    fixedAmount: '0.00'
                    bpsRate: '20'
                    bpsAmount: '0.20'
                    totalAmount: '0.20'
                    currency: usdc
                  platformFee:
                    fixedAmount: '0.00'
                    bpsRate: '20'
                    bpsAmount: '0.20'
                    totalAmount: '0.20'
                    currency: usdc
                source:
                  currency: usdc
                  network: polygon
                  amount: '100.00'
                destination:
                  currency: brl
                  network: pix
                  amount: '545.50'
                  exchangeRate: '5.455'
                expiresAt: '2025-01-01T00:01:00.000Z'
                created: '2025-01-01T00:00:00.000Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    status: 400
                    detail: Invalid request parameters
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    status: 404
                    detail: Resource not found
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '422':
          description: Unprocessable Entity - Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    status: 422
                    detail: Validation failed
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
components:
  schemas:
    CreateQuoteRequestDto:
      type: object
      properties:
        amount:
          description: The quote amount (denominated in source currency).
          example: '100.00'
          pattern: ^\d+(\.\d{2})?$
          type: string
        customerId:
          description: The customer's ID.
          example: customer_3faa484998f44cfead9668608b9ee1f5
          pattern: ^customer_[a-z0-9]+$
          type: string
        source:
          description: The source currency and network for the quote.
          type: object
          properties:
            currency:
              description: >-
                The source currency. For off-ramp: a stablecoin (e.g., "usdc").
                For on-ramp: a fiat currency (e.g., "brl").
              example: usdc
              oneOf:
                - type: string
                  enum:
                    - usdc
                    - usdt
                    - eurc
                - type: string
                  enum:
                    - usd
                    - eur
                    - brl
            network:
              description: >-
                The source network. For off-ramp: a blockchain (e.g.,
                "polygon"). For on-ramp: a payment rail (e.g., "pix").
              example: polygon
              oneOf:
                - type: string
                  enum:
                    - sol
                    - fogo
                    - ethereum
                    - optimism
                    - arbitrum
                    - polygon
                    - base
                    - avalanche
                    - sui
                    - noble
                    - sei
                    - tron
                    - starknet
                    - aptos
                    - hyperliquid
                - type: string
                  enum:
                    - wire
                    - ach
                    - achPush
                    - achPull
                    - swift
                    - sepa
                    - pix
          required:
            - currency
            - network
        destination:
          description: The destination currency and network for the quote.
          type: object
          properties:
            currency:
              description: >-
                The destination currency. For off-ramp: a fiat currency (e.g.,
                "brl"). For on-ramp: a stablecoin (e.g., "usdc").
              example: brl
              oneOf:
                - type: string
                  enum:
                    - usdc
                    - usdt
                    - eurc
                - type: string
                  enum:
                    - usd
                    - eur
                    - brl
            network:
              description: >-
                The destination network. For off-ramp: a payment rail (e.g.,
                "pix"). For on-ramp: a blockchain (e.g., "polygon").
              example: pix
              oneOf:
                - type: string
                  enum:
                    - sol
                    - fogo
                    - ethereum
                    - optimism
                    - arbitrum
                    - polygon
                    - base
                    - avalanche
                    - sui
                    - noble
                    - sei
                    - tron
                    - starknet
                    - aptos
                    - hyperliquid
                - type: string
                  enum:
                    - wire
                    - ach
                    - achPush
                    - achPull
                    - swift
                    - sepa
                    - pix
          required:
            - currency
            - network
        quoteDurationSeconds:
          description: >-
            The duration in seconds for which the quote rate is locked. Defaults
            to 60.
          example: 60
          enum:
            - 30
            - 60
            - 300
          type: number
          default: 60
        integratorBpsFeeRate:
          description: >-
            The integrator BPS fee rate. The BPS rate should be an integer
            represented as a string.
          example: '20'
          type: string
      required:
        - amount
        - customerId
        - source
        - destination
    CreateQuoteResponseDto:
      type: object
      properties:
        id:
          description: A unique identifier for the quote.
          example: quote_d243ab2b1de4447d8a046d87fefe58cf
          pattern: ^quote_[a-z0-9]+$
          type: string
        type:
          description: The transfer type this quote is for.
          example: off_ramp
          type: string
          enum:
            - on_ramp
            - off_ramp
        customerId:
          description: The customer ID.
          example: customer_d243ab2b1de4447d8a046d87fefe58cf
          type: string
        fees:
          type: object
          properties:
            integratorFee:
              description: The integrator fee portion.
              example:
                fixedAmount: '0.00'
                bpsRate: '0'
                totalAmount: '0.00'
                currency: usdc
              type: object
              properties:
                fixedAmount:
                  description: The fixed amount of the fee.
                  example: '1.00'
                  type: string
                bpsRate:
                  description: The BPS rate of the fee.
                  example: '10'
                  type: string
                bpsAmount:
                  description: >-
                    The dollar amount of the BPS-based fee component
                    (sourceAmount × bpsRate / 10000).
                  example: '0.10'
                  type: string
                totalAmount:
                  description: The total amount of the fee applied to the source amount.
                  example: '1.10'
                  type: string
                currency:
                  description: The currency of the fee.
                  example: brl
                  oneOf:
                    - type: string
                      enum:
                        - usdc
                        - usdt
                        - eurc
                    - type: string
                      enum:
                        - usd
                        - eur
                        - brl
              required:
                - fixedAmount
                - bpsRate
                - bpsAmount
                - totalAmount
                - currency
            platformFee:
              description: The platform fee portion.
              example:
                fixedAmount: '0.00'
                bpsRate: '20'
                totalAmount: '2.00'
                currency: usdc
              type: object
              properties:
                fixedAmount:
                  description: The fixed amount of the fee.
                  example: '1.00'
                  type: string
                bpsRate:
                  description: The BPS rate of the fee.
                  example: '10'
                  type: string
                bpsAmount:
                  description: >-
                    The dollar amount of the BPS-based fee component
                    (sourceAmount × bpsRate / 10000).
                  example: '0.10'
                  type: string
                totalAmount:
                  description: The total amount of the fee applied to the source amount.
                  example: '1.10'
                  type: string
                currency:
                  description: The currency of the fee.
                  example: brl
                  oneOf:
                    - type: string
                      enum:
                        - usdc
                        - usdt
                        - eurc
                    - type: string
                      enum:
                        - usd
                        - eur
                        - brl
              required:
                - fixedAmount
                - bpsRate
                - bpsAmount
                - totalAmount
                - currency
          required:
            - integratorFee
            - platformFee
        source:
          type: object
          properties:
            currency:
              description: The source currency.
              example: usdc
              oneOf:
                - type: string
                  enum:
                    - usdc
                    - usdt
                    - eurc
                - type: string
                  enum:
                    - usd
                    - eur
                    - brl
            network:
              description: The source network.
              example: polygon
              oneOf:
                - type: string
                  enum:
                    - sol
                    - fogo
                    - ethereum
                    - optimism
                    - arbitrum
                    - polygon
                    - base
                    - avalanche
                    - sui
                    - noble
                    - sei
                    - tron
                    - starknet
                    - aptos
                    - hyperliquid
                - type: string
                  enum:
                    - wire
                    - ach
                    - achPush
                    - achPull
                    - swift
                    - sepa
                    - pix
            amount:
              description: The source amount.
              example: '100.00'
              type: string
          required:
            - currency
            - network
            - amount
        destination:
          type: object
          properties:
            currency:
              description: The destination currency.
              example: brl
              oneOf:
                - type: string
                  enum:
                    - usdc
                    - usdt
                    - eurc
                - type: string
                  enum:
                    - usd
                    - eur
                    - brl
            network:
              description: The destination network.
              example: pix
              oneOf:
                - type: string
                  enum:
                    - sol
                    - fogo
                    - ethereum
                    - optimism
                    - arbitrum
                    - polygon
                    - base
                    - avalanche
                    - sui
                    - noble
                    - sei
                    - tron
                    - starknet
                    - aptos
                    - hyperliquid
                - type: string
                  enum:
                    - wire
                    - ach
                    - achPush
                    - achPull
                    - swift
                    - sepa
                    - pix
            amount:
              description: The destination amount after exchange.
              example: '545.50'
              type: string
            exchangeRate:
              description: The exchange rate applied to convert source to destination.
              example: '5.455'
              type: string
          required:
            - currency
            - network
            - amount
            - exchangeRate
        expiresAt:
          description: The datetime when this quote expires.
          example: '2025-01-01T00:01:00.000Z'
          type: string
          format: date-time
        created:
          description: The datetime the quote was created.
          example: '2025-01-01T00:00:00.000Z'
          type: string
          format: date-time
      required:
        - id
        - type
        - customerId
        - fees
        - source
        - destination
        - expiresAt
        - created
    ProblemDetailsDto:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
              pointer:
                type: string
              parameter:
                type: string
              header:
                type: string
            required:
              - detail
        correlationId:
          type: string
      required:
        - status
        - detail
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````