# CrestRate API

> CrestRate is a foreign-exchange rate API for businesses that charge or pay across currencies. On every request it compares multiple independent rate sources and returns the rate most favourable to the caller — the highest when charging a customer, the lowest when paying out — clamped so it never drifts far from the live market. Markup is configurable per API key, and lockable quotes make the price shown the price settled.

## At a glance

- **Who it is for:** any business that prices in one currency and settles in another, whether it is collecting money or paying it out (for example prices in JPY, USD, EUR, settled in HKD, CNY, USD, JPY). There is no single target industry; see Use cases below.
- **The problem it solves:** at any moment, rate providers publish different numbers for the same currency pair. A typical rate API hands you whichever number its single vendor publishes. CrestRate compares them and picks the one in the caller's favour.
- **You choose which side the rate favours:** `strategy=max` (default) favours the party charging, `strategy=min` favours the party paying, `strategy=median` is neutral. The response field `side` (`charge` or `pay`) states which side was applied.
- **Guarded in both directions:** the selected rate is capped (when too high) or floored (when too low) relative to the freshest available market anchor, so prices stay defensible if a customer or counterparty checks them against a public converter. The goal is to stop donating the spread, not to overcharge or underpay.
- **Per-key markup:** each API key can carry its own markup in basis points (0–1000 bps, 100 bps = 1%), with optional per-currency overrides. Changes take effect immediately.
- **Lockable quotes:** `POST /v1/quotes` freezes a payable amount and its markup for a fixed window, so exchange-rate movement or a markup change between display and payment cannot cause mismatched totals.
- **Transparency:** every response discloses which source was chosen, what every other source reported, and why any source was excluded. Sources are identified by stable anonymous IDs such as `source_a`.
- **Precision:** every rate and amount is a decimal string, never a JSON number, to avoid floating-point rounding errors in money calculations.
- **Free tier:** 1,000 requests/month, no card required.

## Use cases

- **Cross-border e-commerce** — convert list prices into the customer's currency at checkout.
- **SaaS and subscriptions** — bill each customer in their local currency from one price list.
- **Visitor spending in Japan** — hotels, retail, duty-free shops and point-of-sale systems price in yen while visitors pay in Hong Kong dollars, yuan, US dollars or euros.
- **B2B import and export** — invoice in the buyer's currency and lock the rate for the offer's validity window.
- **Platforms and marketplaces** — charge buyers with `strategy=max` and pay sellers out with `strategy=min` through the same API.
- **Travel, study-abroad and visa agencies** — quote fees in the client's currency.
- **Games and digital goods** — set regional prices in local currencies.

## What it is not

- CrestRate is **not** a bank, payment processor, money transmitter, or broker. It does not move, hold, or convert money.
- The rates are **reference data**, not a dealable or guaranteed price.
- CrestRate does not provide financial, investment, tax, or legal advice.
- It does not process card payments or payouts. Businesses use their own payment provider or bank to move money, and use CrestRate to decide the amount to charge or pay.

## Access

- **Base URL:** `https://api.crestrate.com/v1`.
- **Every API request requires an API key** (`X-API-Key: <key>` or `Authorization: Bearer <key>`). There is no anonymous API access. Keys are created in the dashboard; the Free plan needs no card.
- **Website demo:** the live demo on the CrestRate home page is for evaluation only. Its data is **delayed by 1 hour** (3600 seconds), it is rate-limited and protected by a bot check, and it is not an API — do not integrate against it.

## Choosing which side the rate favours

The `strategy` parameter tells the API whether you are collecting or paying. It sets the side, and the side decides the direction of selection, markup, and rounding.

- `strategy=max` (default) → side `charge`: pick the highest rate. For charging customers — e-commerce, SaaS, hotels, B2B invoicing. Markup moves the rate up; `payable` rounds up.
- `strategy=min` → side `pay`: pick the lowest rate. For paying out — marketplace seller payouts, overseas suppliers. Markup moves the rate down; `payable` rounds down.
- `strategy=median` → side `charge`: pick the source closest to the median. Neutral; for bookkeeping and internal reporting.

`gain_vs_mid` on `/v1/convert` is always the difference in the caller's favour (larger is better): `payable - mid_payable` when charging, `mid_payable - payable` when paying.

## Per-key markup

- Configured in the dashboard for each API key: one default markup, plus optional overrides per `quote` currency (for example HKD 120 bps, JPY 200 bps).
- Unit: basis points, 100 bps = 1%. Range 0 to 1000 bps (0% to 10%).
- Precedence: the key's per-currency override, then the key's default, then the platform default. The response field `markup_source` reports which applied (`key_currency`, `key_default`, `platform`, or `none` for same-currency pairs).
- Direction follows the side: when charging, markup raises the rate and the customer pays more; when paying, markup lowers the rate and you pay out less. Rounding follows the side as well.
- Changes apply from the next request. Quotes already issued keep the markup locked in at creation.
- The dashboard previews the effect of a markup before saving.
- Where markups must be disclosed (for example consumer payments in the EU), the business is responsible for disclosing its markup to its customers.

Worked example (illustrative numbers, not live rates): a US$1,000 order settled in Hong Kong dollars at a rate of 7.8000, with a markup of 150 bps (1.5%). For comparison both cases assume the same selected rate.

- No markup: HK$7,800.00.
- Charging (`strategy=max`): the rate becomes 7.9170 and the customer pays HK$7,917.00 — HK$117.00 more collected.
- Paying (`strategy=min`): the rate becomes 7.6830 and you pay HK$7,683.00 — HK$117.00 less paid out.

## How the rate is chosen

1. Each source's table is normalised to a common base, and the requested pair is computed as a cross rate.
2. Sources whose data is stale or that do not cover the pair are dropped.
3. A freshness anchor is taken from the freshest tier available — real-time, then hourly, then daily — as the best estimate of the current market.
4. Sources deviating from the anchor beyond a fault threshold are dropped as broken data.
5. A surviving rate is selected according to `strategy` (highest, lowest, or closest to the median), then capped or floored relative to the anchor.
6. The markup for the calling API key is applied last, in the direction of the side.

If too few sources agree, the API returns HTTP 503 (`no_rate`) instead of an untrustworthy number. Callers should fall back to their own reference rate, never treat it as zero.

## Measured value

Figures below were computed from live data at 2026-10-26 00:31 UTC across 12 currency pairs. They move with the market.

- Rate sources disagreed by a median of **0.22%** on the same pair at the same moment, and by up to **0.44%**.
- Selecting the most favourable source instead of the median source was worth a median of **0.097%** per order, and up to **0.23%**.
- The second figure — best vs. median, not best vs. worst — is the honest estimate of what a business charging its customers gains over a typical single-source rate API. Best vs. worst would overstate it roughly threefold. It excludes any markup the caller configures.

## Pricing

- **Free** — $0: 1,000 requests/month, 2 requests/second, no card required
- **Starter** — $9/month (or $90/year, two months free): 50,000 requests/month, 10 requests/second
- **Business** — $29/month (or $290/year, two months free): 300,000 requests/month, 30 requests/second
- **Scale** — $79/month (or $790/year, two months free): 2,000,000 requests/month, 100 requests/second
- **Enterprise** — custom pricing: unlimited requests, SLA, contact sales@crestrate.com

Exceeding a monthly quota returns HTTP 429 (`quota_exceeded`). There is no overage billing; requests are blocked until the next calendar month (UTC) or an upgrade.

## Docs

- [API reference](https://crestrate.com/docs): every endpoint, request parameter, response field, and error code.
- [Quickstart](https://crestrate.com/quickstart): copy-paste examples in curl, JavaScript, Python, and PHP.
- [OpenAPI 3.1 specification](https://api.crestrate.com/openapi.json): machine-readable; generated from the running service so it matches the implementation.
- [Full text for language models](https://crestrate.com/llms-full.txt): this summary plus the complete API reference in one file.

## Company and policies

- [Pricing](https://crestrate.com/pricing)
- [Service status](https://crestrate.com/status)
- [Terms of Service](https://crestrate.com/legal/terms)
- [Privacy Policy](https://crestrate.com/legal/privacy): the service does not log which currency pairs or amounts a customer queries.
- [Refund Policy](https://crestrate.com/legal/refund): full refund within 14 days of a first paid subscription.
- Support: support@crestrate.com

## Frequently asked

**Does CrestRate process payments?** No. It returns exchange rates and payable amounts; the business's own payment provider or bank moves the money.

**Can it be used for paying out, not only for charging?** Yes. Call it with `strategy=min`: it selects the lowest rate, applies markup downwards, and rounds amounts down.

**Is the "most favourable" rate unfair to the other party?** The selected rate is capped and floored relative to the live market anchor, so it stays within a defensible range of public reference rates. It removes the arbitrary disadvantage of relying on a single vendor's number. Markup is a separate, explicit setting chosen by the business.

**Which currencies are supported?** Real-time data is available for USD, JPY, EUR, HKD and CNY, in any base and quote combination. Real-time data temporarily unavailable: TWD, SGD, GBP, AUD, KRW, MYR and THB. These will open once their data is stable; until then requests for them return HTTP 422 (`currency_not_available`).

**Can I try it without an API key?** Only through the demo on the website, which shows data delayed by 1 hour. Every API request needs a key; the Free plan (1,000 requests/month) requires no card.

**How fresh is the data?** The freshest sources refresh several times per hour. Every response reports each source's own publication time so callers can judge freshness.

**What happens if a source fails?** It is excluded automatically and the remaining sources cover for it. The response says which sources were used.