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

# Quote a cross-chain deposit

> Prices a deposit for a source (wallet, chain, token), a destination (wallet, chain, token) and an amount. The answer is a signed quote: send the WHOLE object back, unchanged, to build the transaction.

<Warning>**Production, real money.** This endpoint runs on live routes: the transaction you build moves real funds the moment the user signs it, and every hash you see is a real one. There is no crypto sandbox. Use a small amount to try it.</Warning>


## OpenAPI

````yaml https://backend.rheon.io/openapi.json post /v1/deposit/quote
openapi: 3.1.0
info:
  title: Rheon partner API
  version: 1.0.0
  description: >-
    The /v1 surface a partner's backend calls with an API key.


    **Authentication.** Every route takes `Authorization: Bearer <key>`. One
    kind of key: it carries its permissions and limits, and works from your
    server, a page, or this playground alike - where it is called from is not
    checked. Treat it as a secret all the same: anyone holding it acts under its
    permissions until it is rotated.


    **Rate limit.** Counted per key, at the requests-per-second rate configured
    on the key - never per IP, so your users do not throttle each other. Over
    it: `429 rate_limited`.


    **Amounts.** Token amounts are decimal strings in the token's smallest unit;
    fiat amounts are decimal strings in major units. Never JSON numbers.


    **Errors.** One envelope everywhere: `{ error: { code, message } }`, with
    `fields` added on bank refusals that named a field. A body that is not valid
    JSON answers `400 invalid_request`; an endpoint that does not exist answers
    `404 not_found`; a deployment with no partner keys configured answers `404
    not_configured` for all of /v1.


    **Environment.** Every response carries `environment` as its first field:
    `sandbox` or `production`, derived from the upstreams this deployment is
    configured against (never a flag). Read it off any response you paste into a
    ticket. In `sandbox` no real money moves and the card corridor is the
    provider's sandbox asset, which differs from production - read it from GET
    /v1/config, not from these docs.


    **Card corridor.** The asset and chain a card purchase settles as are fixed
    per deployment, not chosen per request. GET /v1/config reports the one
    actually configured.
servers:
  - url: https://api.rheon.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Configuration
  - name: Crypto deposits
  - name: Orders
  - name: Cards
  - name: Bank transfers
  - name: Virtual accounts
  - name: Reference
  - name: Sandbox only
paths:
  /v1/deposit/quote:
    post:
      tags:
        - Crypto deposits
      summary: Quote a cross-chain deposit
      description: >-
        Prices a deposit for a source (wallet, chain, token), a destination
        (wallet, chain, token) and an amount. The answer is a signed quote: send
        the WHOLE object back, unchanged, to build the transaction.
      operationId: depositQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositQuoteRequest'
      responses:
        '200':
          description: The signed quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedQuoteOutput'
        '400':
          description: >-
            Cannot quote this.


            - `invalid_request`: A field is missing or malformed: amount not a
            digit string, an address not an EVM address, a chain not a positive
            integer, method not "crypto", amountMode not exact-in/target-out,
            destination.chain or destination.token omitted.

            - `no_route`: No route has enough liquidity for this pair and amount
            right now. Try a smaller amount or try again later.
          x-error-codes:
            - invalid_request
            - no_route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: >-
            No usable API key.


            - `unauthorized`: Missing, malformed or unknown key. One
            undifferentiated answer on purpose.
          x-error-codes:
            - unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            Refused by the key's scope.


            - `permission_denied`: The key does not carry the `deposits`
            permission.

            - `chain_not_allowed`: The key is not enabled for that chain on that
            side.

            - `token_not_allowed`: The key is not enabled for that token on that
            chain.
          x-error-codes:
            - permission_denied
            - chain_not_allowed
            - token_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: >-
            Over this key's rate.


            - `rate_limited`: More requests per second than the key is
            configured for. Counted PER KEY (all your users share one bucket),
            never per IP.
          x-error-codes:
            - rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            Our fault.


            - `internal`: Unexpected server error. Detail is in our logs, never
            on the wire.
          x-error-codes:
            - internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - bearerAuth: []
components:
  schemas:
    DepositQuoteRequest:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/DepositSource'
        destination:
          $ref: '#/components/schemas/DepositDestination'
        amount:
          $ref: '#/components/schemas/AmountSmallestUnit'
          description: >-
            The amount, in the smallest unit of whichever token `amountMode`
            selects: the source token for exact-in, the destination token for
            target-out. Must be greater than zero.
        amountMode:
          $ref: '#/components/schemas/AmountMode'
        method:
          type: string
          const: crypto
          description: Funding method. Only "crypto" is supported on this route.
      required:
        - source
        - destination
        - amount
        - method
    SignedQuoteOutput:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        provider:
          type: string
          description: >-
            Opaque identifier of the route source. Pass it back unchanged on
            /v1/deposit/status.
          example: sprinter
        outAmount:
          type: string
          pattern: ^\d+$
          description: >-
            Expected amount delivered at the destination, smallest unit of the
            destination token. Under target-out this is a FLOOR: bridges deliver
            at least this, usually a little more.
          example: '4999750'
        validUntil:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Unix seconds after which the quote is refused with quote_expired.
            Set by us: at most five minutes from issue, or the provider's sooner
            deadline.
          example: 1788799278
        executionDurationSeconds:
          description: >-
            How long the provider ESTIMATES the transfer takes, in seconds. Not
            a quote deadline. Absent when the provider does not state one.
          type: number
        payload:
          description: >-
            Opaque provider data needed to build the transaction. Do not inspect
            or modify; its shape differs per provider and is not a contract.
        rheonCorridor:
          type: object
          properties:
            sourceChain:
              $ref: '#/components/schemas/ChainId'
            destChain:
              $ref: '#/components/schemas/ChainId'
          required:
            - sourceChain
            - destChain
          additionalProperties: false
          description: >-
            The chains this quote moves between, written by us and covered by
            the signature. Do not alter.
        rheonTransfer:
          type: object
          properties:
            fromAddress:
              $ref: '#/components/schemas/EvmAddress'
            toAddress:
              $ref: '#/components/schemas/EvmAddress'
            sourceChain:
              $ref: '#/components/schemas/ChainId'
            sourceToken:
              $ref: '#/components/schemas/EvmAddress'
            destChain:
              $ref: '#/components/schemas/ChainId'
            destToken:
              $ref: '#/components/schemas/EvmAddress'
            amount:
              type: string
              pattern: ^\d+$
              description: Decimal string in the token's smallest unit.
              example: '4980000'
            amountMode:
              $ref: '#/components/schemas/AmountMode'
          required:
            - fromAddress
            - toAddress
            - sourceChain
            - sourceToken
            - destChain
            - destToken
            - amount
            - amountMode
          additionalProperties: false
          description: >-
            What was asked for, echoed by us (addresses lower-cased) and covered
            by the signature. Do not alter.
        rheonClient:
          type: string
          description: >-
            The API client this quote was issued to. A quote is only accepted
            back by the key it was issued to.
          example: acme
        rheonSig:
          type: string
          description: >-
            Our signature over every other field. A quote that does not verify,
            or was altered anywhere, is refused.
          example: 5cdc0af7861b267c45c0feec1cd2689278c94d70a53108c8c1226da055a6e25e
      required:
        - environment
        - provider
        - outAmount
        - validUntil
        - payload
        - rheonCorridor
        - rheonTransfer
        - rheonClient
        - rheonSig
      additionalProperties: false
      description: >-
        A quote we issued. Send the WHOLE object back as `quote`, exactly as
        returned - every field is covered by the signature. The `environment`
        field every response starts with may come back with it; it is not part
        of the signature and is ignored on the way in.
    ErrorEnvelope:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Machine-readable error code. Branch on this, never on the
                message.
              example: invalid_request
            message:
              type: string
              description: Human-readable explanation. Wording may change.
              example: amount must be a decimal string of the token's smallest unit.
            fields:
              description: >-
                Per-field complaints from the bank provider, when it named the
                field it refused (bank routes only). Field names, never values.
              example:
                applicantInfo.nationality: iso3166_1_alpha2
              type: object
              propertyNames:
                type: string
              additionalProperties:
                type: string
          required:
            - code
            - message
          additionalProperties: false
      required:
        - environment
        - error
      additionalProperties: false
      description: The one error shape this API produces.
    DepositSource:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/EvmAddress'
          description: The wallet that signs and funds the transfer.
        chain:
          $ref: '#/components/schemas/ChainId'
          description: Source chain id.
          example: 8453
        token:
          $ref: '#/components/schemas/EvmAddress'
          description: Source token contract address on `chain`.
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      required:
        - address
        - chain
        - token
      description: Where the funds come from.
    DepositDestination:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/EvmAddress'
          description: >-
            Recipient wallet where the funds land. May differ from the source
            wallet.
          example: '0x2222222222222222222222222222222222222222'
        chain:
          $ref: '#/components/schemas/ChainId'
          description: >-
            Landing chain id. REQUIRED: a missing chain is refused by name
            (destination.chain is required).
        token:
          $ref: '#/components/schemas/EvmAddress'
          description: >-
            Landing token contract address ON `chain`. REQUIRED: a missing token
            is refused by name (destination.token is required).
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
      required:
        - address
        - chain
        - token
      description: Where the funds go.
    AmountSmallestUnit:
      type: string
      pattern: ^\d+$
      description: >-
        Decimal string in the token's smallest unit (e.g. "5000000" = 5 USDC at
        6 decimals). Digits only: no sign, no decimal point, never a JSON
        number.
      example: '5000000'
    AmountMode:
      type: string
      enum:
        - exact-in
        - target-out
      description: >-
        Which side `amount` pins down. `exact-in` (the default when omitted):
        the payer spends exactly `amount` of the source token. `target-out`: at
        least `amount` of the destination token must land, and the payer's side
        flexes. Any other value is refused rather than defaulted.
    Environment:
      type: string
      enum:
        - sandbox
        - production
      description: >-
        Which environment answered. `sandbox`: at least one money upstream is
        the provider's sandbox - no real money moves there, and the card
        corridor is the sandbox's asset (read GET /v1/config), not the
        documented production one. `production`: every configured upstream is
        real. Derived from the configured upstream hosts at boot, never a flag.
      example: sandbox
    ChainId:
      type: integer
      exclusiveMinimum: 0
      maximum: 9007199254740991
      description: EVM chain id, a positive integer (e.g. 42161 for Arbitrum One).
      example: 42161
    EvmAddress:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      description: >-
        EVM address: 0x followed by 40 hex characters. Checksum casing is not
        required.
      example: '0x1111111111111111111111111111111111111111'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key, issued by us and shown once at creation.

````