MetalflowAPI — Live Precious Metals Prices

The official MetalflowAPI WordPress plugin makes it dead simple to embed live precious metals prices on any WordPress site — perfect for jewelers, publishers, trade-in calculators and bullion shops. Features

• Spot prices for Gold (XAU), Silver (XAG), Platinum (XPT) and Palladium (XPD) — near real-time on paid plans, delayed on the Free plan
• Carat-aware pricing for 9k, 10k, 14k, 18k, 20k, 21k, 22k and 24k Gold
• 30+ currencies — EUR, USD, GBP, JPY, CHF, CAD, AUD, PLN, CZK, INR, BRL, CNY and many more (sourced daily from European Central Bank)
• Units: gram (g), kilogram (kg), troy ounce (ozt)
• 7 shortcodes — drop into any post, page or widget
• 5 Gutenberg blocks — Live Price, Carat Calculator, Ticker, Carat Table, Historical Chart
• Sidebar widget — classic widget for the metals ticker
• Server-side only — your API key stays on the server, never exposed to the browser
• Smart, plan-aware caching — one shared request per page, 6-hour cache on the Free plan, last known prices shown if the API is unreachable
• Plan & usage box — see your monthly request usage in Settings → MetalflowAPI, with a warning at 80% and 100%
• Interactive history chart — 7D / 1M / 6M / 1Y / 5Y / Max range buttons, price and date axes, hover/keyboard tooltip, responsive, no external JavaScript libraries (paid plans; ranges follow your plan's history depth)
• Theme-adaptive by default — widgets inherit your theme's font, text and link colours (theme.json presets) and adapt to dark themes and dark backgrounds
• Easy customisation — global Appearance settings (style preset card / minimal / borderless, accent, text, background, border, up/down colours, corner radius, text size) with live preview; per-block colour, typography, spacing and border controls; shortcode attributes
• Optional "Powered by" bonus — off by default. If you choose to show a small "Prices by MetalflowAPI" link (once per page), Free-plan sites get 2,000 requests/month instead of 500 and fresher prices once the link is verified
• Translation-ready — all strings localized

Shortcodes [metalflow_price metal="Gold" currency="EUR" unit="g"] — spot price for one metal [metalflow_carat carat="14" currency="EUR" unit="g"] — carat-aware Gold price [metalflow_ticker currency="EUR" unit="g" style="minimal"] — all 4 metals [metalflow_table currency="EUR" unit="g"] — full carat table 9k–24k [metalflow_change metal="Gold" days="30"] — % change over N days (Starter and above) [metalflow_calc currency="EUR"] — interactive carat-weight calculator [metalflow_chart metal="Gold" currency="EUR" range="1y" ranges="7d,1m,6m,1y,5y,max"] — interactive history chart with range buttons (paid plans) Chart attributes

• range — default range: 7d, 1m, 6m, 1y, 5y or max (default from Settings, normally 1y; older values such as 30d, 90d, 2y still work)
• ranges — which buttons to show, comma separated (default from Settings)
• metal, currency, unit (g, kg, ozt), height (80–600 px, default 220), fill="0" (no area fill), label="0" (hide title/price/change header)

Ranges longer than your plan's history (Free 30 days, Starter 5 years, Pro 30 years) are hidden from visitors; administrators see them with a lock and a link to the plans. The default range is rendered with the page; other ranges load on click from your own site (/wp-json/metalflowapi/v1/chart, which only serves charts that appear on your site, from the server-side cache). Styling attributes (all shortcodes)

• style — card, minimal or borderless
• color (or accent) — accent / chart line colour, e.g. color="#b8860b"
• text, bg, border — text, background and border colours (hex)
• up, down — colours for rising / falling prices (hex)
• radius — corner radius in px (0–32)
• size — text size scale (0.75–1.5)

Example: [metalflow_ticker style="minimal" color="#b8860b"], [metalflow_chart range="1m" style="borderless" color="#2563eb" radius="12"]. Invalid values are ignored. Without attributes, widgets use Settings → MetalflowAPI → Appearance, and with that left empty they follow your theme. Pricing The plugin is 100% free. Prices come from the MetalflowAPI service, which has a free tier (no credit card required):

• Free — personal & non-commercial sites only. 500 requests/month, delayed prices, 10 currencies, 30-day history. The price change and chart widgets are not included (they stay hidden from visitors).
• Starter — €9/mo for commercial sites (shops, jewelers, dealers). 10,000 requests/month, fresher prices, 30 currencies, 5-year history, change endpoint.
• Pro — €29/mo, 100,000 requests, 30-year history, all currencies.
• Enterprise — custom, full 1968+ history.

Current plans: metalflowapi.com/pricing EU & GDPR Servers in Strasbourg (France). All data within EU. GDPR-compliant. EUR billing with VAT invoices. External services This plugin connects to the MetalflowAPI service (metalflowapi.com, operated by MetalflowAPI) to fetch precious metals prices. It is required for live data; without an API key the plugin makes no requests at all. Terms of Service: https://metalflowapi.com/legal/terms · Privacy Policy: https://metalflowapi.com/legal/privacy Price data (only after you add or register an API key). Requests are made from your WordPress server — never from your visitors' browsers — when a page with a MetalflowAPI shortcode, block or widget is rendered and the cached copy has expired, and when you click "Test connection". Endpoints:

• https://metalflowapi.com/api/v1/latest — spot prices (shortcodes metalflow_price, metalflow_ticker, the Live Price/Ticker blocks and the ticker widget)
• https://metalflowapi.com/api/v1/carat — gold carat prices (metalflow_carat, metalflow_table, metalflow_calc and the carat blocks)
• https://metalflowapi.com/api/v1/change — % change (metalflow_change)
• https://metalflowapi.com/api/v1/timeframe — daily prices for the 7D, 1M, 6M and 1Y chart ranges (metalflow_chart, Historical Chart block)
• https://metalflowapi.com/api/v1/sparkline — long-range price curve for the 5Y and Max chart ranges (also used if your plan does not include /timeframe)
• https://metalflowapi.com/api/v1/symbols — key check and currency list on the settings page

Sent with each request: your API key (X-API-Key header), the query parameters needed for the widget (metal, currency, unit, date range, chart size/colour) and a User-Agent with the plugin and WordPress version numbers (it does not contain your site address). Your server's IP address is visible to the service, as with any HTTP request. Nothing about your visitors (IP addresses, cookies, behaviour), posts, comments or users is sent. Optional in-dashboard registration (Settings → MetalflowAPI → "Get your free API key"). Only when you type your email address and click "Send code", the plugin sends that email address, this site's URL and the plugin version to https://metalflowapi.com/api/plugin/request-code. When you enter the 6-digit code it sends your email address and the code to https://metalflowapi.com/api/plugin/verify-code. This creates your free MetalflowAPI account and returns your API key, which is saved in your site's WordPress options. Optional "Powered by MetalflowAPI" bonus (off by default). Only after you tick "Show a 'Powered by MetalflowAPI' link…" in Settings → MetalflowAPI and save (or click "Register this site"), the plugin sends this site's address (home URL), the address of one public page of your site that shows a MetalflowAPI widget (if known), the plugin version and your API key (X-API-Key header) to https://metalflowapi.com/api/plugin/poweredby (POST). MetalflowAPI then loads that homepage/page — right away and about once a day — only to check that the "Prices by MetalflowAPI" link is there; on the Free plan a verified link raises your monthly limit to 2,000 requests and gives fresher prices. The settings page asks the same endpoint for the verification status (GET, at most every 10 minutes while you view the page). When you untick the option, the plugin asks the endpoint to delete the registration (DELETE). Nothing is sent while the option is off. Chart ranges in the browser. When a visitor clicks a chart range button, the browser asks your own site (/wp-json/metalflowapi/v1/chart), not metalflowapi.com. That endpoint only accepts the metal/currency/unit combinations of charts rendered on your site (signed) and the six fixed ranges, answers from the server-side cache (one API request per range per cache period: at least 30 minutes for 7D/1M, 1 hour for 6M/1Y, 6 hours for 5Y/Max) and never exposes your API key. Caching. Responses are cached on your server with WordPress transients: on the Free plan (delayed prices) for 6 hours (1 hour with an active "Powered by" bonus), on paid plans for the configured time (default 5 minutes, never shorter than the plan's own refresh interval). Errors are cached briefly (a quota error until the time given by the service), and the last successful response is kept so visitors see the last known price, with its date, while the service is unreachable. Links. Links to metalflowapi.com in the WordPress admin (sign-up, pricing, dashboard) carry utm_* parameters and the plugin version so MetalflowAPI can see which plugin version a visit came from. Nothing is sent until you click such a link. The optional "Prices by MetalflowAPI" link on the public site is off by default; when you enable it, it is a plain link to metalflowapi.com (the gold price page of your default currency) without tracking parameters, shown once per page.

1.3.0

• New: optional "Powered by MetalflowAPI" bonus program (off by default). When you enable it, one followed link "Prices by MetalflowAPI" is shown per page (under the first widget, or in the footer if the page only has inline prices), pointing to metalflowapi.com or the gold price page of your currency — no tracking parameters. On the Free plan a verified link gives 2,000 requests/month instead of 500 and fresher prices.
• New: enabling the option registers this site for verification at https://metalflowapi.com/api/plugin/poweredby; disabling it removes the registration (see External services). Settings → MetalflowAPI shows the status: pending, verified (bonus active) or link not found, with a "Check status" button.
• Improved: the Plan & usage box uses the monthly limit sent by the service (X-RateLimit-Month-Limit), so the percentage is right with the bonus or custom limits; with the bonus active, Free-plan prices are cached for 1 hour instead of 6 hours.
• Changed: the old per-widget "Powered by metalflowapi.com" credit is replaced by the single link above (sites that had the credit enabled keep showing the link; registering for the bonus needs one click on "Register this site").

1.2.0

• New: interactive history chart — range buttons 7D / 1M / 6M / 1Y / 5Y / Max (choose the default and which buttons show in Settings, the block or range= / ranges=), min/max price and start/end date axes, tooltip with date and price on hover, touch and arrow keys, responsive, accessible (real buttons with aria-pressed, text summary for screen readers). Small vanilla script, no external libraries.
• New: chart data per range — 7D–1Y from /timeframe (daily prices), 5Y/Max from /sparkline. One API request per range, cached server-side with a plan-aware lifetime. The default range comes with the page; other ranges load on click through a strict, signed, cached endpoint on your own site (/wp-json/metalflowapi/v1/chart) that accepts only fixed values — it is not a proxy.
• New: plan-aware ranges — ranges beyond your plan's history are hidden from visitors; administrators see them locked with a link to the plans.
• New: theme-adaptive styling — widgets inherit the theme's font, text and link colours (theme.json presets) and adapt to dark themes and dark backgrounds.
• New: Settings → MetalflowAPI → Appearance — style preset (card / minimal / borderless), accent, text, background, border and up/down colours (colour picker), corner radius, text size, chart defaults, with a live light/dark preview.
• New: per-block styling — core colour, typography, spacing and border controls plus a "Widget style" panel (preset, accent, up/down colours, radius) on all blocks.
• New: styling attributes on all shortcodes — style, color/accent, text, bg, border, up, down, radius, size (all values validated; invalid values are ignored).
• Improved: sample data for editors (no API key) now shows a realistic price history for every range.
• Improved: ticker, carat table and calculator fit narrow columns and sidebars.
• Changed: chart width attribute is no longer needed (the chart fills its container); old range values (30d, 90d, 2y, …) are mapped to the new ranges.
• Kept from 1.1.2: no public API proxy, plan-aware caching, last-known prices when the API is unavailable, "delayed" label on the Free plan, nothing shown to visitors without an API key.

1.1.2

• Security: removed the public REST proxy /wp-json/metalflowapi/v1/data (it let anyone use the site's API key and quota) and the /calc endpoint. The carat calculator now computes in the browser from prices rendered into the page, so it also works on sites with plain permalinks.
• Reliability: 5-second API timeout; errors are cached briefly (quota errors until Retry-After) instead of calling the API on every page view; the last good price is shown with an "as of" date while the API is unavailable; widgets on the same page share one request (USD/EUR/GBP tickers need one call instead of four).
• Quota: cache time follows your plan — 6 hours on the Free plan (delayed prices), the configured value on paid plans (never shorter than the plan's refresh interval). Cache flush now works with persistent object caches (Redis/Memcached).
• Free plan: data is labelled "delayed" instead of "live spot". The change and chart widgets (not in the Free plan) are hidden from visitors; editors see a short note with a link to plans.
• No API key: visitors see nothing; sample data is shown only to logged-in editors (previously visitors could see sample prices).
• Admin: new "Plan & usage" box on the settings page; notices at 80% and 100% of the monthly quota, for a rejected key and for features not in your plan. Notices appear only on the Dashboard, Plugins and MetalflowAPI screens and stay dismissed.
• Admin: one sign-up flow (email + 6-digit code); existing customers get a link to copy their key from metalflowapi.com/dashboard/keys, also when the email already has an account. API key field is masked.
• WordPress.org compliance: tested up to 7.1, requires 6.3 (block API v3), escaped block/widget output, translator comments, inline nonce checks, translatable block editor labels, complete uninstall (incl. multisite), External services section lists the real endpoints; User-Agent no longer contains the site URL.

1.1.1

• New: "Default currency" is now a dropdown of currency codes with names (live list from your plan when an API key is set, otherwise the ~30 ECB currencies). Choose "Other (type code)…" to enter any ISO 4217 code by hand. Existing saved values keep working.
• New: "Default unit" (troy ounce / gram / kilogram) is now sent to the API as unit= on /latest and /carat; prices are no longer converted client-side. Labels show the unit (e.g. "per gram").
• New: unit attribute for [metalflow_ticker], the Ticker block and the Ticker widget (defaults to the Default unit setting). The unit is part of the cache key.
• Fix: currency codes are sanitised server-side to exactly three uppercase letters.

1.1.0

• New: get your free API key without leaving WordPress. On Settings → MetalflowAPI, enter your email, click "Send code", type the 6-digit code from the email and the key is saved automatically, followed by a test fetch of the latest gold price. A "Get a key on metalflowapi.com" link remains as a fallback.
• Privacy: only when you click "Send code" the plugin sends your email address, this site's URL and the plugin version to metalflowapi.com (see External Service Disclosure). Nothing is sent before that.

1.0.9

• New: prominent "Get free API key" button on the settings page while no key is set. The signup links carry utm_source=wp-plugin and the plugin version so we can see which plugin versions bring users (no data is sent from your site unless you click the link).
• Docs: Free plan is now 500 requests/month.

1.0.8

• Fix: plugin now uses the commerce API (/api/v1) so dashboard keys (mfk_live_*) from metalflowapi.com/dashboard/keys work correctly. Previous versions incorrectly called the internal WordPress REST API (/wp-json/metals/v1), which rejected dashboard keys with "Invalid API key".

1.0.7

• Fix: "Test connection" now uses the API key typed in the settings field (no need to save first).

1.0.6

• New: offline "Sample data" preview. With no API key configured, widgets now render static sample values (clearly labelled) so you can see how everything looks before signing up. No network request is made and no data is sent in this mode.
• WP.org review: block editor scripts now register their WordPress core dependencies (wp-blocks, wp-element, wp-block-editor, wp-components, wp-server-side-render, wp-i18n) via wp_register_script() and block.json, instead of manually enqueuing core "wp-" handles.
• Clarified output-escaping comments in block render templates (output is escaped/sanitized inside the renderer).

1.0.5

• WP.org review: admin CSS/JS moved to enqueued assets (no inline tags).
• Sparkline SVG sanitized with wp_kses before output.
• "Powered by" credit is off by default — explicit opt-in only.
• Contributors updated; removed redundant load_plugin_textdomain() call.

1.0.4

• NEW [metalflow_chart] shortcode + "Historical Chart" Gutenberg block — server-side SVG sparkline for any metal/currency, from 30 days up to the full 58-year archive. Light/dark theme, custom width/height, gradient fill, last-value label.
• Plan history depth is honoured automatically — Free clamps to 30 days, Starter to 5 years, Pro to 30 years, Enterprise to full 1968+.

1.0.3

• Live Price block / shortcode now renders the unit suffix (e.g. "€2,089.45/g") so the unit attribute is visible at a glance.

1.0.2

• Backward-compat: orphan top-level options set via WP-CLI (mfapi_api_key, mfapi_default_currency etc.) are now auto-migrated into the canonical mfapi_settings array.

1.0.1

• Fixed API key placeholder in admin settings to show correct key prefix (mfk_live_...).

1.0.0

• Initial release.
• 6 shortcodes: price, carat, ticker, table, change, calc.
• 4 Gutenberg blocks (Live Price, Carat Calculator, Ticker, Carat Table).
• Sidebar widget.
• REST proxy /wp-json/metalflowapi/v1/data and /calc.
• Server-side transient caching.
• Settings page with connection tester and cache flush.
• Translation-ready (i18n).