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

# The quotation object

A quotation is the price of one movement, worked out before you make it. It carries what you send, what the recipient ends up with, every charge as its own line, and the rate when a currency changed.

Asking for one is free and commits you to nothing. What makes it more than an estimate is `quote_id`: send it with a payout and the payout settles at exactly these figures, until `quote_expires_at` passes.

Which shape comes back depends on the version you are pinned to. The itemized one below is the current shape; the older grouped one is at the end of this page.

## Example

```json theme={null}
{
  "quote_id": "dddddddd-eeee-ffff-0000-111111111111",
  "quote_expires_at": "2026-09-01T12:15:00.000Z",
  "source": { "amount": 100000, "currency": "USD", "precision": 2 },
  "recipient": { "amount": 98650, "currency": "USD", "precision": 2 },
  "pricing_context": {
    "tier": "tier_2",
    "starting_tier": "tier_2",
    "intro_period_active": false,
    "transactional_waived": false,
    "month_cumulative": 4500000,
    "month_cumulative_currency": "USD",
    "from_held_balance": false
  },
  "conversion": {
    "pair": "USD/USD",
    "rate": "1.000000",
    "source_amount": 100000,
    "source_currency": "USD",
    "target_amount": 100000,
    "target_currency": "USD",
    "rate_source": "fallback_at_peg",
    "market_rate": "1.000000",
    "clamp": "passthrough",
    "locked_at": "2026-09-01T12:00:00.000Z",
    "ttl_seconds": 900
  },
  "fees": [
    {
      "kind": "fixed",
      "code": "wire_domestic_outbound",
      "status": "active",
      "version": "v3",
      "deprecated_at": null,
      "charged_by": "kira",
      "amount": 1000,
      "currency": "USD",
      "precision": 2
    },
    {
      "kind": "percentage",
      "code": "inbound",
      "status": "active",
      "version": "v3",
      "deprecated_at": null,
      "charged_by": "kira",
      "amount": 250,
      "currency": "USD",
      "precision": 2,
      "calculation_method": "percentage",
      "rate_bps": 25,
      "basis_amount": 100000,
      "basis_currency": "USD"
    },
    {
      "kind": "fixed",
      "code": "client_markup_fixed",
      "status": "active",
      "version": "v1",
      "deprecated_at": null,
      "charged_by": "client",
      "amount": 100,
      "currency": "USD",
      "precision": 2
    }
  ],
  "totals": {
    "kira_revenue_total": 1250,
    "client_markup_total": 100,
    "fee_total": 1350,
    "source_net_amount": 98650,
    "currency": "USD",
    "precision": 2
  }
}
```

<Note>
  **Every amount is a whole number in the currency's smallest unit**, with the `precision` to divide by. `1000.00` USD arrives as `amount: 100000` with `precision: 2`. Rates are decimal strings.
</Note>

## What the quotation is

| Field                | Type                   | Description                                                                                                                                                                                         |
| -------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quote_id`           | string, uuid or `null` | Send it with a payout to settle at this price. `null` on a `quote_for` quote, which is a preview and is not saved.                                                                                  |
| `quote_expires_at`   | string, date-time      | When the price stops holding, ISO 8601.                                                                                                                                                             |
| `balance_sufficient` | boolean                | Whether the balance you hold covered `source.amount` when the quote was priced. Only on a quote against a balance you already hold, and the balance is checked again for real when the payout runs. |

## The money

`source` is what you send and `recipient` is what the counterparty ends up with. Both carry `amount`, `currency` and `precision`.

| Field                 | Type    | Description                                          |
| --------------------- | ------- | ---------------------------------------------------- |
| `source.amount`       | integer | What leaves, in the smallest unit.                   |
| `source.currency`     | string  | Currency of `source.amount`.                         |
| `source.precision`    | integer | How many decimal places that currency has.           |
| `recipient.amount`    | integer | What arrives, after every charge and any conversion. |
| `recipient.currency`  | string  | Currency of `recipient.amount`.                      |
| `recipient.precision` | integer | How many decimal places that currency has.           |

## The charges

`fees` is one entry per charge. Add them up and you get `totals.fee_total`. The names are the ones your contract uses — [How you're charged](/overview/how-you-are-charged) has what each is for.

| Field           | Type             | Description                                                                                          |
| --------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `kind`          | string           | Which shape the line takes. [Values](/reference/quotations/values#fee-kind)                          |
| `code`          | string           | Names the charge, so you can match the same line across quotes.                                      |
| `status`        | string           | Whether the line is being charged. [Values](/reference/quotations/values#fee-status)                 |
| `version`       | string           | Which revision of the charge was applied.                                                            |
| `deprecated_at` | string or `null` | When the charge stops being used. `null` while it is current.                                        |
| `charged_by`    | string           | Whose charge it is. [Values](/reference/quotations/values#fee-charged_by)                            |
| `amount`        | integer          | The charge, in the smallest unit. Negative on an adjustment line, which credits the difference back. |
| `currency`      | string           | Currency of `amount`.                                                                                |
| `precision`     | integer          | How many decimal places that currency has.                                                           |

A `percentage` line carries three more fields, and a `fixed` line carries none of them:

| Field                | Type    | Description                                               |
| -------------------- | ------- | --------------------------------------------------------- |
| `calculation_method` | string  | Always `percentage`.                                      |
| `rate_bps`           | integer | The rate in basis points. Negative on an adjustment line. |
| `basis_amount`       | integer | The amount the rate was applied to, in the smallest unit. |
| `basis_currency`     | string  | Currency of `basis_amount`.                               |

Not every line appears on every quote. A movement with no currency change carries no conversion line, and a payout from a balance you already hold carries no inbound charge — that was taken when the money arrived.

## The totals

| Field                 | Type    | Description                                        |
| --------------------- | ------- | -------------------------------------------------- |
| `kira_revenue_total`  | integer | Everything charged by Kira.                        |
| `client_markup_total` | integer | Everything charged by you, on top.                 |
| `fee_total`           | integer | Both of the above together.                        |
| `source_net_amount`   | integer | What is left of `source.amount` after the charges. |
| `currency`            | string  | Currency of these totals.                          |
| `precision`           | integer | How many decimal places that currency has.         |

## The conversion

Always present. When no currency changed, it echoes the movement back at a rate of `1.000000` — so compare `source_currency` with `target_currency`, or read `pair`, to tell whether a conversion actually happened.

| Field             | Type              | Description                                                                                                            |
| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `pair`            | string            | What was converted into what.                                                                                          |
| `rate`            | string            | The rate used, as a decimal string with six decimals.                                                                  |
| `market_rate`     | string            | The rate as sampled, before any hold at parity was applied.                                                            |
| `clamp`           | string            | Whether the market rate was held at parity or used as sampled. [Values](/reference/quotations/values#conversion-clamp) |
| `rate_source`     | string            | Where the rate came from. [Values](/reference/quotations/values#conversion-rate_source)                                |
| `source_amount`   | integer           | What went in, in the smallest unit.                                                                                    |
| `source_currency` | string            | Currency of `source_amount`.                                                                                           |
| `target_amount`   | integer           | What came out, in the smallest unit.                                                                                   |
| `target_currency` | string            | Currency of `target_amount`.                                                                                           |
| `locked_at`       | string, date-time | When the rate was fixed, ISO 8601.                                                                                     |
| `ttl_seconds`     | integer           | How long the rate is held, in seconds.                                                                                 |

Both the rate applied and the market rate it came from are here, so the difference is visible rather than buried in one number.

## Why this price

`pricing_context` says what the price was worked out against.

| Field                       | Type    | Description                                                                   |
| --------------------------- | ------- | ----------------------------------------------------------------------------- |
| `tier`                      | string  | The pricing tier applied. [Values](/reference/quotations/values#pricing-tier) |
| `starting_tier`             | string  | The tier you were on before this month's volume was counted.                  |
| `month_cumulative`          | integer | How much has moved this month, which is what decides the tier.                |
| `month_cumulative_currency` | string  | Currency of `month_cumulative`.                                               |
| `intro_period_active`       | boolean | Whether introductory pricing was still running.                               |
| `transactional_waived`      | boolean | Whether the per-transaction charge was waived.                                |
| `from_held_balance`         | boolean | Whether this was priced as a payout from a balance you already hold.          |

## The grouped shape

A quote read on `2026-04-14` comes back grouped rather than itemized, and every amount is a **decimal string** instead of a whole number with a `precision`.

| Field                  | Type              | Description                                                                                   |
| ---------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `amount`               | string            | What you send.                                                                                |
| `currency`             | string            | Currency of `amount`. Always `USD`.                                                           |
| `recipient_amount`     | string            | What the recipient ends up with.                                                              |
| `recipient_currency`   | string            | Currency of `recipient_amount` — `USD` on a bank payout, `USDC` or `USDT` on a wallet payout. |
| `quote_id`             | string, uuid      | Send it with a payout to settle at this price.                                                |
| `quote_expires_at`     | string, date-time | When the price stops holding, ISO 8601.                                                       |
| `payment_instructions` | object            | The funding token and chain, echoed back. Only on a crypto-funded quote.                      |

The charges arrive under `fees`, in groups rather than as lines: `base_fees` is what Kira charged, `client_markup` is what you charged on top, `network_fee` is the chain's transfer cost, and `fx` carries the rates when the quote converts. `fees.total_fees` is `base_fees.total` and `client_markup.total` added up, and `fees.total` repeats it. Neither includes `network_fee`, so add that yourself on a payout delivered as digital currency — it is `0.00` on a bank payout.

The two shapes carry the same charges. What the itemized one adds is a line per charge, each naming what it is and what it was calculated on, instead of a group total you have to take apart.