---
title: "Create a quote"
method: POST
path: "/v0/quotes"
tags: ["Quotes"]
---

# Create a quote

`POST /v0/quotes`

## Request

- Base URL: `https://orchestration.seismic.systems/api`
- URL: `https://orchestration.seismic.systems/api/v0/quotes`
- Auth: API key in header `Api-Key`

Price the requested trade across every eligible rail and return a snapshot ranked best-first. With `?wait=1` the call blocks until pricing completes; otherwise it returns a `pending` snapshot to poll via `GET /v0/quotes/{id}`. With `?named=1` only named options are returned and accepted: the payment reaches the beneficiary under the end customer's own legal name.

## Query parameters

- `wait` boolean
- `named` boolean

## Request body

- CreateQuoteBody: Body for `POST /v0/quotes`.
  - `amount` string, required: Amount to trade, denominated in the currency of the leg named by `amount_leg` (the source leg by default).
  - `amount_leg` 'source' | 'destination': Which leg a quote request's `amount` is denominated in. `Source` fixes what the customer pays ("exact-in", the default); `Destination` fixes what the recipient receives ("exact-out") and prices the required source amount.
  - `destination` union, required: Destination leg of the quote — always a registered account.
    - string, uuid: Bare account id — shorthand for `{ "account": "<id>" }`.
    - object: Registered account, optionally pinned to a subset of its rails. Unknown fields are rejected.
      - `account` string, uuid, required: Id of the registered destination account.
      - `rails` string[]: Rail subset to price — omitting fans out across every rail the account supports.
  - `developer_fee_bps` integer, nullable: Your own developer fee in basis points (100 = 1%), added on top of the quoted rate. At most 999 (9.99%).
  - `developer_fee_flat` string, nullable: Your own flat developer fee, as a decimal string in the source leg's currency (`"1.50"`). Charged in addition to `developer_fee_bps` and shown to your customer as its own fee line. Supported on stablecoin-funded payments; a quote that requests one on an unsupported corridor is rejected rather than priced without it.
  - `end_customer_id` string, uuid, required: The end customer this quote is for.
  - `end_customer_type` 'individual' | 'business' | 'business_individual' | 'org'
  - `payer` QuotePayer: Who is paying a pay-in, as the quote body names them.
    - `bank_code` string, nullable: The code of the bank the payer pays from, in the scheme's own bank list.
    - `document_number` string, nullable: The number of the payer's identity document.
    - `document_type` 'CC' | 'CE' | 'NIT' | 'PASS' | 'PEP': The identity document a Colombian beneficiary is known by. The receiving bank matches the holder against it, so the kind travels with the number.
    - `email` string, nullable
    - `full_name` string, nullable: The payer's full legal name.
    - `phone` string, nullable: The payer's mobile number in E.164 form.
    - `tax_id` string, nullable: The payer's tax id, for rails that credit only a transfer sent under it. ARS: the payer's CUIT/CUIL, 11 digits with no separators (`20123456786`).
  - `source` union, required: One leg of a quote request.
    - string, uuid: Bare account id — shorthand for `{ "account": "<id>" }`. Only valid when the account supports exactly one currency and one rail.
    - object: Account reference with optional disambiguation, or an inline corridor descriptor. At least one of `account` or `currency` must be set.
      - `account` string, uuid: Id of a registered account.
      - `address` string: Inline crypto address, for pricing-only source legs with no account on file.
      - `country_code` string: ISO-2 settlement country override for this leg. Normally derived from the account; not echoed back in responses.
      - `currency` string: Currency code. Required when no `account` is given (inline descriptor); otherwise a disambiguator for accounts spanning multiple currencies.
      - `rails` string[]: Explicit rail ids — e.g. `["ach", "wire"]` or `["base"]`. Omitting fans out across every rail the leg supports.
      - `schemas` string[]: Named rail groups — e.g. `["us_bank"]` — expanded at request time.

## Response `200`

Quote snapshot.

- AsyncQuoteSnapshot: View of a stored quote request: its lifecycle `status`, the ranked `quotes[]` priced so far, and an echo of the resolved request.
  - `best_quote_id` string, uuid, nullable: `id` of the server's recommended quote. Matches `quotes[0].id` today (the array is ranked) — exposed explicitly so clients don't have to depend on the ordering invariant.
  - `created_at` string, date-time, required
  - `id` string, uuid, required
  - `quotes` ApiQuote[], required: Ranked best-first across every eligible rail.
    - `expires_at` string, date-time, nullable
    - `fees` QuoteFees, required: Fee breakdown attached to a quote. `total` is the sum across `items`, denominated in `currency` (typically the source leg's currency — what the caller pays in). When no per-item breakdown is available, `items` is empty and the fee is implicit in the quote's `rate`.
      - `currency` string, required
      - `items` QuoteFeeItem[], required
        - union: Single fee line item on a quote. The `type` field discriminates the variants.
          - object
            - `amount` string, required
            - `currency` string, required
            - `description` string, nullable
            - `type` 'flat', required
          - object
            - `amount` string, required
            - `bps` integer, required
            - `currency` string, required
            - `description` string, nullable
            - `type` 'percentage', required
          - object
            - `amount` string, required
            - `currency` string, required
            - `description` string, nullable
            - `type` 'network', required
          - object
            - `amount` string, required
            - `currency` string, required
            - `description` string, required
            - `type` 'other', required
      - `total` string, required
    - `id` string, uuid, required
    - `in` Leg, required: Resolved leg of a trade — one side, fully materialized. Returned inside a quote's `in` / `out`. `account_id` is always present. A nil UUID means no settlement-ready account backs this leg yet — re-quote with registered accounts before accepting.
      - `account_id` string, uuid, required
      - `address` string, nullable
      - `amount` string, required
      - `currency` string, required
      - `rail` string, required
    - `out` Leg, required: Resolved leg of a trade — one side, fully materialized. Returned inside a quote's `in` / `out`. `account_id` is always present. A nil UUID means no settlement-ready account backs this leg yet — re-quote with registered accounts before accepting.
      - `account_id` string, uuid, required
      - `address` string, nullable
      - `amount` string, required
      - `currency` string, required
      - `rail` string, required
    - `rate` string, required
    - `supported_expired_quote_behaviors` ExpiredQuoteBehavior[], required: Expired-quote behaviors `accept` will honor for this quote via `expired_quote_behavior`. Empty when only the default — the payment is refunded on expiry — applies.
    - `acceptance_requirements` QuoteAcceptanceRequirements, required: Known requirements for accepting this specific quote.
      - `files_required` boolean, required: Attach at least one supporting document in the accept body's `files` when true. Additional documents may be requested during processing.
      - `source_account_number_required` boolean, required: Send the payer's bank account number as the accept body's `source_account_number` when true. When false, accept rejects `source_account_number`.
    - `is_named` boolean, required: Whether this is a named payout: the payment reaches the beneficiary under the end customer's own legal name rather than an intermediary's. Pass `?named=1` when creating the quote to receive only named options.
  - `request` QuoteRequestEcho, required: Echo of the original request carried on the quote snapshot. Legs come back resolved rather than in whichever of the request forms produced them.
    - `amount` string, required
    - `amount_leg` 'source' | 'destination', required: Which leg a quote request's `amount` is denominated in. `Source` fixes what the customer pays ("exact-in", the default); `Destination` fixes what the recipient receives ("exact-out") and prices the required source amount.
    - `destination` QuoteRequestEchoLeg, required: One side of the snapshot's `request` echo: the resolved corridor (`currency` + `rails`), plus the registered account when the leg was account-backed. `account_id` is absent on inline source legs.
      - `account_id` string, uuid, nullable
      - `currency` string, required
      - `rails` string[], required
    - `end_customer_id` string, uuid, required
    - `end_customer_type` 'individual' | 'business' | 'business_individual' | 'org', required
    - `named` boolean, required: Whether the quote was created with `?named=1`. When `true`, `quotes` holds only named options and accept takes only a named one.
    - `payer` QuotePayer: Who is paying a pay-in, as the quote body names them.
      - `bank_code` string, nullable: The code of the bank the payer pays from, in the scheme's own bank list.
      - `document_number` string, nullable: The number of the payer's identity document.
      - `document_type` 'CC' | 'CE' | 'NIT' | 'PASS' | 'PEP': The identity document a Colombian beneficiary is known by. The receiving bank matches the holder against it, so the kind travels with the number.
      - `email` string, nullable
      - `full_name` string, nullable: The payer's full legal name.
      - `phone` string, nullable: The payer's mobile number in E.164 form.
      - `tax_id` string, nullable: The payer's tax id, for rails that credit only a transfer sent under it. ARS: the payer's CUIT/CUIL, 11 digits with no separators (`20123456786`).
    - `source` QuoteRequestEchoLeg, required: One side of the snapshot's `request` echo: the resolved corridor (`currency` + `rails`), plus the registered account when the leg was account-backed. `account_id` is absent on inline source legs.
      - `account_id` string, uuid, nullable
      - `currency` string, required
      - `rails` string[], required
  - `status` 'pending' | 'ready' | 'expired', required

## Other responses

- `400`: Malformed or invalid request body, a `named` value other than `1`, `true`, `yes`, `on`, `0`, `false`, `no` or `off` (case-insensitive), or an end customer whose verification isn't yet approved for any route that could settle the payment.
- `401`: Missing or invalid API key.
- `404`: `end_customer_id` is unknown.
- `422`: No rail supports the requested corridor, or no rate is available, or `?named=1` was passed and no eligible route can be named (`NoNamedQuote`). Also returned when `destination.account` is an external bank account that isn't registered for payouts yet because its holder is missing `account_holder.relationship` or `account_holder.industry`: one `missing` violation per field, and the message links the account's dashboard page and names the `PATCH …/holder` call, either of which adds them.
- `503`: With `Retry-After`, nothing was stored and the same request can be retried after it (with `?named=1`, the routes that could be named were briefly unavailable). Without, the `wait=1` snapshot is final but could not be fully priced: create a new quote.

---

[API](https://skmtc.dev/seismic/apis/seismic-orchestration-api.md) - [All operations](https://skmtc.dev/seismic/apis/seismic-orchestration-api/llms.txt) - [OpenAPI document](https://skmtc.dev/seismic/apis/seismic-orchestration-api/revisions/08ada1f159fa?raw)