Chinese Renminbi Yuan (CNY) Price Today — USD/CNY live rate and conversion examples for APIs

You need today’s USD/CNY rate in your app so you can price a product in yuan, convert CNY receipts to USD for P&L, or trigger a hedge when the renminbi moves. In this guide you’ll fetch the live USD/CNY quote with Metals-API, understand the rate fields, compute conversions in both directions, and add a lightweight time-series check to monitor intraday changes—all with copy-pasteable examples.

What you’ll build (and why the field names matter)

With a single “latest” call, you’ll read two rate fields you’ll actually use for Chinese yuan:

• rates.CNY — how many CNY you get for 1 USD (CNY per USD)
• rates.USDCNY — how many USD you get for 1 CNY (USD per CNY)

Why both? Many applications store prices in a base currency (often USD) but need to show converted values to end users (CNY). Some workflows, like reconciling CNY cash balances back to USD, go the other way. Having both directions avoids rounding drift and makes intent crystal clear.

You’ll also see how to cache responses safely, handle timestamp/time zone, and query a short time window for change detection without over-polling.

Symbols and conventions for CNY

Metals-API returns all rates by default with base: USD. For currencies:

• CNY — the Chinese renminbi (yuan) currency code
• USDCNY — USD per 1 CNY (the inverse of CNY per 1 USD)

If you’re new to Metals-API, skim the symbol list for currency codes and metal tickers at Metals-API Supported Symbols. For endpoint capabilities and parameters used below, see the Metals-API Documentation.

Fetch the live USD/CNY quote

Use the Latest Rates endpoint. Request only the symbols you need to reduce payload size and simplify parsing:

curl -s "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=CNY,USDCNY"

A successful response includes the base currency, a UNIX timestamp, an ISO date, and a rates object. Below is a real response for USD/CNY from the API; use the exact field names when parsing:

{"success":true,"timestamp":1791508080,"date":"2026-10-09","base":"USD","rates":{"CNY":6.7024,"USD":1,"USDCNY":0.14920028646455002}}

What you’ll use:

• timestamp — UNIX epoch seconds for when rates were calculated. Treat this as UTC.
• date — a YYYY-MM-DD convenience date.
• base — the currency against which rates are quoted; default is USD.
• rates.CNY — CNY per 1 USD (example: 6.7024 CNY = 1 USD).
• rates.USDCNY — USD per 1 CNY (example: ≈ 0.1492002865 USD = 1 CNY).

If your UX or ledger prefers one direction only, pick the explicit field (CNY or USDCNY) rather than inverting to avoid tiny rounding differences across systems.

Python example: convert both directions using the live rate

This example calls the same Latest endpoint, parses CNY and USDCNY, and converts an order priced in USD to CNY for checkout and a CNY balance back to USD for treasury reporting.

import os
import requests
from decimal import Decimal, ROUND_HALF_UP

API_KEY = os.getenv("METALS_API_KEY", "YOUR_API_KEY")
URL = "https://metals-api.com/api/latest"

params = {
"access_key": API_KEY,
"symbols": "CNY,USDCNY"
}

r = requests.get(URL, params=params, timeout=10)
r.raise_for_status()
data = r.json()

if not data.get("success"):
raise SystemExit(f"API error: {data}")

timestamp = data["timestamp"] # UNIX seconds, UTC
date = data["date"] # 'YYYY-MM-DD'
base = data["base"] # 'USD'
cny_per_usd = Decimal(str(data["rates"]["CNY"])) # CNY per 1 USD
usd_per_cny = Decimal(str(data["rates"]["USDCNY"])) # USD per 1 CNY

# Example 1: Price a USD 129.99 item in CNY for checkout
usd_price = Decimal("129.99")
cny_price = (usd_price * cny_per_usd).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

# Example 2: Convert a CNY 250,000 cash balance to USD for reporting
cny_balance = Decimal("250000")
usd_balance = (cny_balance * usd_per_cny).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

print(f"As of {date} (ts={timestamp}, base={base}):")
print(f"1 USD = {cny_per_usd} CNY")
print(f"1 CNY = {usd_per_cny} USD")
print("")
print(f"USD {usd_price} => CNY {cny_price}")
print(f"CNY {cny_balance} => USD {usd_balance}")

Notes:

• Use Decimal to avoid binary float rounding in prices and P&L.
• Round with your business rules (e.g., 2 decimals for CNY for retail, more for treasury).
• Persist timestamp/date alongside your conversions for auditability and reconciliation.

Monitor intraday USD/CNY changes with a small time window

For simple “did USD/CNY move today?” checks without maintaining your own tick store, query a short historical window and compute deltas. Two practical approaches:

• Time-series endpoint: returns daily historical rates for dates you choose. Parse start and end to compute change.
• Fluctuation endpoint: returns start_rate, end_rate, and change fields directly.

Example: get a 7-day window (daily bars)

Daily snapshots are appropriate for dashboards or batch jobs. Replace dates as needed and request CNY and USDCNY together for both directions.

curl -s "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&start_date=2026-10-03&end_date=2026-10-09&symbols=CNY,USDCNY"

Interpretation tips:

• “rates” is keyed by date; each contains CNY per USD and USD per CNY for that date.
• Weekends and market holidays: some dates may be absent or unchanged; handle sparse days.
• Compute pct change as (end - start) / start for the specific direction you use in your app.

Example: ask the API to compute day-over-day fluctuation

For a quick numeric summary you can alert on, use fluctuation. The API returns start_rate, end_rate, change, and change_pct.

curl -s "https://metals-api.com/api/fluctuation?access_key=YOUR_API_KEY&start_date=2026-10-08&end_date=2026-10-09&symbols=CNY,USDCNY"

Use change_pct thresholds to trigger notifications or circuit breakers for pricing updates.

Practical integration details you’ll want on day one

• Base currency and inversion: With base=USD, rates.CNY is “CNY per 1 USD.” The paired rates.USDCNY is “USD per 1 CNY.” Prefer the explicit field over manual inversion for stability.
• Timestamps and timezone: timestamp is UNIX seconds in UTC. Store it with your conversions (along with the ISO date) for downstream matching and P&L audits.
• Caching and polling: Latest updates at an interval that depends on plan. Cache responses for at least the documented update interval and include ETag/If-Modified-Since semantics in your client if you implement conditional requests. For intraday apps, a simple memoization layer keyed by minute granularity prevents accidental hammering.
• Weekends/market closures: CNY is affected by onshore (CNY) and offshore (CNH) liquidity and holidays. Expect fewer or unchanged snapshots on weekends and holidays. In your UI, explain that the last-timestamp applies when markets are closed, rather than implying “live” ticks.
• Error handling: Check success in the payload before reading rates. On transient HTTP errors, back off and retry with jitter. On hard failures, continue with last-known-good until a freshness timeout you define (e.g., 30–60 minutes for retail price tags, shorter for trading tools).
• Precision and rounding: Use Decimal for finance. If your system requires specific scale (e.g., 4 places for rates, 2 for retail prices), normalize immediately after conversion and before persistence.
• Auditability: Log the full payload SHA/ETag, timestamp, and the exact symbol set requested. This makes ledger reconciliation across microservices predictable.

End-to-end conversion patterns you can ship today

1) Price a USD catalog in CNY at checkout

1. Call latest with symbols=CNY,USDCNY.
2. For each USD price, multiply by rates.CNY and round to 0.01 for display.
3. Persist the rate, timestamp, and converted value to your order so refunds and adjustments use the same rate later.

2) Consolidate a CNY ledger to USD for daily P&L

1. Call latest near your ledger cut-off time.
2. Multiply each CNY ledger balance by rates.USDCNY and store the USD equivalent and timestamp.
3. Keep the day’s rate fixed in reports to avoid post-close drift.

3) Alert when USD/CNY moves more than X% today

1. Fetch a two-day fluctuation for CNY and USDCNY.
2. Alert when abs(change_pct) > threshold in the direction your business cares about.
3. Throttle notifications to avoid spam (e.g., send once per day per symbol).

Where to find symbols, docs, and your API key

• Browse supported symbols and naming conventions: Symbols
• Learn endpoint parameters and response formats: Documentation
• Get an API key to run the examples: Register
• If you need managed connectivity or additional program access, see MCP

Note: There is no free trial. If copper pricing is your focus, the Copper Monthly offering is available at $19.99/month. For current plan capabilities and update intervals, check the documentation and your account dashboard after registering.

Design guidance for production systems

• Idempotency: Wrap rate reads and conversions in idempotent jobs keyed by (symbol set, minute bucket). This prevents accidental duplicate writes in retry storms.
• Data contracts: Model a RateQuote object with fields (base, symbol, value, timestamp, date, source). Reuse it across services for pricing, treasury, and analytics.
• Fail-quietly UX: When rates are stale, add “as of HH:MM UTC” near converted numbers. For carts and checkouts, lock rate at confirmation and display it on the invoice.
• Testing: Snapshot test parsing against the exact JSON structure shown above. Include cases where one or more symbols are missing or success=false.
• Security: Keep your API key outside code (env vars, secrets manager). Send requests over HTTPS only.

Reference: directionality and quick sanity checks

• If rates.CNY ≈ 6–8, then rates.USDCNY should be ≈ 1/that (0.12–0.17). Comparing them is a fast integration sanity check.
• When presenting changes, compare like-with-like. If your UI shows CNY per USD, compute changes on CNY, not USDCNY, to avoid sign confusion.
• If you store both directions, always mark which one you applied in conversions to simplify audits.

Additional resources

• Metals-API home: metals-api.com
• People’s Bank of China exchange-rate information: pbc.gov.cn
• Reuters USD/CNY coverage for macro context: reuters.com/markets/currencies

FAQ

Q: What’s the difference between CNY and USDCNY fields?
A: With base=USD, rates.CNY is CNY per 1 USD. rates.USDCNY is USD per 1 CNY (the inverse). Pick the field that matches the direction of your calculation to avoid inverting and rounding manually.

Q: How often should I call the Latest endpoint for USD/CNY?
A: Poll at or below the update interval for your plan and cache results for at least that long. Many apps that only need displayed prices (e.g., retail) refresh every 10–15 minutes; trading tools may require more frequent updates depending on plan.

Q: How do I handle weekends and holidays?
A: Expect fewer or unchanged updates. Your client should display “as of” timestamps and continue using the last-known-good rate until the next refresh. For alerts, use the time-series or fluctuation endpoints over business days rather than expecting continuous weekend movement.

Q: Can I convert amounts without calling a separate convert endpoint?
A: Yes. Most apps multiply by rates.CNY (USD→CNY) or rates.USDCNY (CNY→USD) from the Latest response. That keeps one consistent snapshot across all conversions in a request cycle.

Q: Do I need to worry about units like troy ounces here?
A: Units like “per troy ounce” apply to metal symbols (e.g., XAU). For fiat currencies such as CNY and USD, values are unitless exchange rates. Still, treat them with appropriate decimal precision in finance operations.

Get your API key and ship your USD/CNY integration today. Create your account at Register, then explore endpoints and parameters in the Documentation. If you need program access or connectivity options, see MCP.