# SpotMetal: Automated Precious Metals Pricing & Buyback Engine for Shopify
> The complete software platform for fine jewelers, bullion dealers, and scrap recyclers on Shopify.

SpotMetal connects Shopify stores to live global commodity feeds (Gold XAU, Silver XAG, Platinum XPT, Palladium XPD) and automatically recalculates catalog prices, safeguards wholesale margins with hard price floors, and powers turnkey storefront customer scrap buybacks with 1-click Draft Order payouts.

## Core Capabilities & Architecture

- **Live Commodities Sync:** Sub-minute automated spot price ingestion via LBMA and ECB feeds.
- **Dynamic Karat Formula Engine:** Multi-karat purity multipliers (8K to 24K, 925 Sterling Silver), gram weight normalization, tiered fabrication brackets, and craftsmanship making charges.
- **Margin Floor Safeguards:** Hard `minimumPrice` bounds preventing below-cost catalog selling during market flash crashes.
- **Circular Buyback System:** Turnkey customer scrap trade-in appraisal calculators, `BB-*` shadow inventory, and 1-click Shopify Draft Order generation.
- **Omnichannel Retail Branch Stocks:** Multi-location physical inventory allocation and storefront store availability badges.
- **Tax & Audit Compliance:** EU §25a UStG differential margin taxation and immutable audit logging.

## API & Tool Discovery

- **MCP Server Card:** [https://spotmetal.qbytesoft.com/.well-known/mcp.json](https://spotmetal.qbytesoft.com/.well-known/mcp.json)
- **AI Plugin Manifest:** [https://spotmetal.qbytesoft.com/.well-known/ai-plugin.json](https://spotmetal.qbytesoft.com/.well-known/ai-plugin.json)
- **OpenAgent Manifest:** [https://spotmetal.qbytesoft.com/.well-known/agent.json](https://spotmetal.qbytesoft.com/.well-known/agent.json)
- **Full Knowledge Repository:** [https://spotmetal.qbytesoft.com/llms-full.txt](https://spotmetal.qbytesoft.com/llms-full.txt)

## Documentation Wiki Guides

### 1. Getting Started
- [Installation & Shopify OAuth Setup](https://spotmetal.qbytesoft.com/docs/installation-and-onboarding): Step-by-step guide to installing SpotMetal from the Shopify App Store.
- [Understanding Core Concepts](https://spotmetal.qbytesoft.com/docs/understanding-spotmetal): Spot feeds, Karat purities, Margin floors, and the Circular Buyback Loop.
- [5-Step Quick Start Checklist](https://spotmetal.qbytesoft.com/docs/quick-start-checklist): Go from installation to a fully live-priced product catalog in 10 minutes.

### 2. Rate Feeds & Currency
- [System Default vs Custom API Keys](https://spotmetal.qbytesoft.com/docs/default-vs-custom-api): Choose between pre-integrated Edelmetalle.de feeds and private API subscriptions.
- [AES-256 Encrypted Credential Vault](https://spotmetal.qbytesoft.com/docs/encrypted-api-credentials): How your private market data provider API keys are securely protected.
- [Multi-Currency FX & Manual Locks](https://spotmetal.qbytesoft.com/docs/currency-fx-and-overrides): Lock exchange rates to hedge against currency fluctuations across 15+ markets.

### 3. Pricing Formula Engine
- [Formula Mathematical Model](https://spotmetal.qbytesoft.com/docs/formula-basics-and-math): The core formula: Material Value + Premium + Fixed Fabrication & Labor.
- [Karat Multipliers (8K–24K)](https://spotmetal.qbytesoft.com/docs/karat-purity-multipliers): Exact purity factors from 0.333 to 0.999 fine gold and silver conversion.
- [Tiered Weight Brackets](https://spotmetal.qbytesoft.com/docs/tiered-weight-brackets): Scale percentage margins dynamically based on gram mass brackets.
- [Minimum Price Floor Safeguards](https://spotmetal.qbytesoft.com/docs/price-floors-and-skipping): Prevent accidental below-cost selling during sudden market flash crashes.
- [Collector & Numismatic Exemptions](https://spotmetal.qbytesoft.com/docs/collector-coin-exemptions): Bypass spot rate updates for rare collector coins and fixed antique jewelry.

### 4. Storefront Theme Extensions
- [Embedding Live Spot Ticker Marquee](https://spotmetal.qbytesoft.com/docs/live-ticker-marquee): Add a 60fps auto-scrolling ticker bar into your Shopify theme header or footer.
- [Storefront Buyback Calculator Widget](https://spotmetal.qbytesoft.com/docs/buyback-calculator-widget): Embed customer appraisal modals on your product or dedicated trade-in pages.
- [PDP Trade-In Quick Submission Form](https://spotmetal.qbytesoft.com/docs/product-buyback-popup): Turn product pages into double-sided selling and acquisition hubs.
- [Retail Location & Trade-In Availability](https://spotmetal.qbytesoft.com/docs/physical-location-availability): Display in-store bullion availability and local trade-in appraisal desks.

### 5. Circular Buyback System
- [Shadow Products & SKU Architecture](https://spotmetal.qbytesoft.com/docs/shadow-products-architecture): How SpotMetal creates shadow appraisal items with BB-* SKU codes at $0.00.
- [Customer Submission & App Proxy Flow](https://spotmetal.qbytesoft.com/docs/customer-inquiry-workflow): From storefront form submission to the admin review queue via App Proxy.
- [1-Click Shopify Draft Order Payouts](https://spotmetal.qbytesoft.com/docs/draft-order-creation): Issue official customer payout invoices and credit receipts in seconds.

### 6. Compliance & Differential Tax
- [Differential Taxation (§25a UStG)](https://spotmetal.qbytesoft.com/docs/differential-taxation-25a): Configure European margin-scheme VAT rules for vintage jewelry and bullion.
- [Immutable Audit Trails & GDPR](https://spotmetal.qbytesoft.com/docs/audit-trail-and-security): Full audit logs of every spot rate sync, formula edit, and buyback payout.

### 7. Troubleshooting & FAQs
- [GraphQL Rate Limits & Sync Lag](https://spotmetal.qbytesoft.com/docs/sync-lag-and-api-limits): How SpotMetal batches mutations to stay within Shopify API leaky bucket limits.
- [Error Codes Reference & Solutions](https://spotmetal.qbytesoft.com/docs/common-error-codes): PRICE_FLOOR_BOUND, API_AUTH_FAILED, and METAFIELD_SYNC_LAG explanations.