Documentation

Complete reference for the Commodity Markets Capital platform, including user guides, protocol mathematics, and API endpoints.

Overview

Commodity Markets Capital (CMC) documentation provides a comprehensive guide to the current browser-local preview and the proposed architecture for launching community tokens paired with commodity quote coins.

Crucial Distinction: Current vs Proposed

Active Product: The currently available interface is strictly a browser-local preview. It relies entirely on browser storage, illustrative balances, and indicative pricing. It does not connect to live contracts, move real funds, or require cryptographic signatures.

Proposed Product: The documentation outlines theoretical onchain smart contracts, PancakeSwap V2 integration, and real-time live trading. None of these are deployed or active.

The launched asset is a community token. It is not a commodity, a synthetic commodity, or a claim on any real-world physical asset. There are no guarantees of price pegs, redemption, or backing.

User Guide

Launch Validation

Creating a new local market preview requires specific field formatting to ensure compatibility with intended network targets.

Field	Validation Rules
Name	3 to 80 characters. Trimmed.
Ticker	2 to 10 characters. Must contain only ASCII letters and numbers. Automatically uppercased.
Description	Optional. Maximum 1000 characters.
Links (Web/X/Telegram)	Optional. Must start with http:// or https://, have a valid hostname/URL, contain no credentials. Maximum 2048 characters.
Image	Optional. PNG, JPEG, or WebP only. Maximum size 4 MB. Uploaded images become publicly accessible immediately.

Commodity Modes

The launch interface allows pairing the community token with either a single commodity or a basket. The catalog contains various items across Metals, Energy, Agriculture, Livestock, Fast food, CS2, Game gold, Trading cards, Water, Cars, and Currencies. (Note: The explicit "Drugs" category is excluded).

Single Mode

Permits exactly one valid catalog symbol. The curve utilizes the item's fixed illustrative USD conversion reference rather than real-time live prices.

Basket Mode

Select between 1 and 5 distinct symbols. The interface visually weights them equally. The curve utilizes a normalized reference of exactly $1 illustrative USD, completely independent of the aggregate catalog component prices.

Buy & Sell Steps

Interacting with a local market preview follows these strict deterministic operations:

Select Operation: Choose to Buy (spending local USD to receive tokens) or Sell (burning local tokens to receive USD).
Input Amount: Enter the desired gross USD or token amount. The system automatically subtracts the selected fee (1-3%) during calculation.
Curve Guardrails: The trade is calculated against the constant-product curve. A buy will be outright rejected if the required output exceeds the curve's 800,000,000 token limit or if your browser-local balance is insufficient. Graduation is explicitly blocked by these guardrails.
Local Execution: Click to execute. The interface applies the math, updates your browser's local ledger, and adjusts the local quote reserve. No signature or onchain transaction takes place.

Local Wallet Integration

The connected wallet interface acts only as a display layer. Under the hood, a browser-local practice wallet initializes with exactly $10,000 USD of illustrative local currency.

Storage Risk: Balances, tokens, and history exist strictly in your browser's localStorage. Clearing site data permanently deletes these local preview records.
Initial Buy: Launching a market requires an initial buy of at least $1. The interface defaults to $25. This amount cannot exceed your current browser-local USD balance.
No Transactions: Approving a launch or trade explicitly costs no blockchain transaction fees and requires no wallet signatures.

Curve and Math

The illustrative market relies on a specific set of constants and modified constant-product equations.

Supply Constants

TOTAL_SUPPLY = 1,000,000,000
CURVE_SUPPLY = 800,000,000
RESERVED_SUPPLY = 200,000,000
OPENING_TARGET = $5,000 USD equivalent
GRADUATION_TARGET = $35,000 USD equivalent

Pricing Equations

Virtual Start and Initial Reserve

The curve initializes with a virtual token supply based on the square root of 7.

typescript

const V0 = 800_000_000 / (1 - 1 / Math.sqrt(7));
// Initial quote reserve scaled by USD conversion
const q0 = (5000 / 1_000_000_000) * V0 / pairUSD;

Buy Logic

Buys use a constant-product formula. The requested USD amount is reduced by the fee to determine the net input.

typescript

const netQuote = (usdAmount - fee) / pairUSD;
const tokenOut = tokenReserve - (tokenReserve * quoteReserve) / (quoteReserve + netQuote);

Sell Logic

Sells calculate the gross quote output, then apply the fee against the resulting USD value. Fees are not added back to reserves.

typescript

const grossQuote = quoteReserve - (tokenReserve * quoteReserve) / (tokenReserve + tokenAmount);
const grossUsd = grossQuote * pairUSD;
const fee = grossUsd * feeRate;
const netUsd = grossUsd - fee;

Worked Numerical Example

Consider a new launch in Basket mode (where pairUSD = 1) with a default $25 USD buy and a 1% fee.

1. Calculate Virtual Start (V0):

V0 = 800,000,000 / (1 - 1 / √7)

V0 ≈ 800,000,000 / 0.6220355 = 1,286,100,564.71 tokens

2. Calculate Initial Quote Reserve (q0):

q0 = (5,000 / 1,000,000,000) * 1,286,100,564.71 / 1

q0 = 0.000005 * 1,286,100,564.71 ≈ 6,430.50 quote assets

3. Execute $25 Buy with 1% Fee:

Net Quote = ($25 - $0.25) / 1 = 24.75

TokenOut = V0 - (V0 * q0) / (q0 + Net Quote)

TokenOut = 1,286,100,564.71 - (1,286,100,564.71 * 6,430.50) / (6,430.50 + 24.75)

TokenOut = 1,286,100,564.71 - (8,270,273,181,818.18 / 6,455.25)

TokenOut = 1,286,100,564.71 - 1,281,170,083.54 = 4,930,481.17 tokens

Fees and Allocations

Markets configure a static trading fee between 1% and 3% in 0.1% increments. The UI displays an intended split structure:

40% Holders
30% Buyback
30% Treasury

Important Note: This split is strictly an accounting label in this preview. The platform does not currently distribute rewards, provide yield, process automatic buybacks, or execute burns. Actual burn balances remain zero.

Provider Coverage

Prices are sourced strictly from free-tier public endpoints with no subscription mechanisms. No endpoint accepts private keys or credentials.

Category / Provider	Symbols	Unit & Frequency	Source
Metals (Gold API)	GLD, SILV, PLAT, PALL, COPP	USD / troy oz (Copper: / lb) Current / Indicative	gold-api.com
FX (Frankfurter/ECB)	EUR, JPY	Base USD Daily Reference	frankfurter.dev
Energy (U.S. EIA via FRED)	WTI, BRENT, NGAS, GASO, HEAT	Barrel / MMBtu / Gallon Daily Government	fred.stlouisfed.org

Unavailable Assets

The following catalogue symbols represent display-only or theoretical components. They explicitly return an unavailable status from the API. Future integration with licensed providers (e.g. Barchart, Trading Economics) is pending legal and subscription approval.

ALUM, LUMB, WHEAT, CORN, SOY, SOYO, RICE, OATS, COFF, COCO, COTT, SUGAR, CATTLE, HOGS, FEED, BURG, FRIES, PIZZA, CS2, GP, TCG, WATER, CAR

API Reference

The public API provides system health, quote routing, and image storage services. No authentication keys are required. All responses use JSON unless otherwise specified.

Domains and Examples

The documentation snippets below use app.example.com or api.example.com as explicit domain placeholders to illustrate HTTP calls. In practice, you must query the exact host your frontend is running on. Upload requests enforce a strict Same-Origin Policy if the Origin header is present. Do not blindly copy-paste the example domains into your production code.

GET /network/bsc

Read-only BSC mainnet connectivity check. The server calls only eth_chainId and eth_blockNumber through its private RPC configuration; this is not a general RPC proxy. Returns 200 when chain 56 and a block number are verified, or 503 when unconfigured, unavailable, or on the wrong chain. Results and failures are cached for 30 seconds per process; HTTP responses use no-store. No credentials or upstream error details are returned.

javascript

const response = await fetch('/network/bsc');
const status = await response.json();
// connected: boolean
// chainId: 56 on success, otherwise null
// blockNumber: number on success, otherwise null
// checkedAt: ISO timestamp
// tradingEnabled: false
// message: human-readable connectivity status
if (!response.ok) throw new Error(status.message);

GET

/api/healthz

Returns the current health status of the API server.

bash

curl https://api.example.com/api/healthz

json

{
  "status": "ok"
}

GET

/market-data/quotes

Fetches combined quotes from external free-tier public providers. Upstream providers are not guaranteed and some catalogue symbols may return an "unavailable" status. Results are cached in-process for 30 seconds (even failures are cached to prevent flooding). HTTP responses use Cache-Control: no-store. Provider failures are represented in a 200 response with an unavailable quote status. Use /market-data/quotes on this app’s origin, not /api/market-data/quotes; health and storage use the /api prefix.

Quote Field Reference (CommodityQuote)

Field	Type	Description
symbol	string	The catalogue identifier (e.g. GLD, WTI)
priceUSD	number \| null	Current unit price in USD, if available.
changePercent	number \| null	Percentage change, if available.
changePeriod	"previous business day" \| null	The timeline for the change percent.
status	"current" \| "daily" \| "reference" \| "unavailable"	The freshness and availability state of the feed.
source	string \| null	Human-readable provider name (e.g. Gold API).
sourceUrl	string \| null	The URL to the data provider.
updatedAt	string \| null	ISO-8601 or YYYY-MM-DD timestamp from the provider.
message	string	Contextual message or warning regarding the data.

bash

curl https://app.example.com/market-data/quotes

json

{
  "quotes": {
    "GLD": {
      "symbol": "GLD",
      "priceUSD": 2345.60,
      "changePercent": null,
      "changePeriod": null,
      "status": "current",
      "source": "Gold API",
      "sourceUrl": "https://gold-api.com/",
      "updatedAt": "2024-05-20T12:00:00Z",
      "message": "Latest indicative provider quote. Precious metals: USD per troy oz..."
    },
    "EUR": {
      "symbol": "EUR",
      "priceUSD": 1.085,
      "changePercent": -0.12,
      "changePeriod": "previous business day",
      "status": "daily",
      "source": "Frankfurter / ECB",
      "sourceUrl": "https://frankfurter.dev/",
      "updatedAt": "2024-05-19",
      "message": "Daily reference rate dated 2024-05-19, not a real-time FX quote."
    },
    "CORN": {
      "symbol": "CORN",
      "priceUSD": null,
      "changePercent": null,
      "changePeriod": null,
      "status": "unavailable",
      "source": null,
      "sourceUrl": null,
      "updatedAt": null,
      "message": "Feed not connected"
    }
  },
  "fetchedAt": "2024-05-20T12:00:05.000Z",
  "refreshAfterMs": 30000
}

POST

/api/storage/token-images

Uploads a raw binary image for a token market. Required to be a direct file upload (no multipart wrapper). It employs a shared rate limit budget of 60 uploads per 15 minutes, shared by all callers only per process (does not use IP headers). Maximum size is 4 MiB.

javascript

// Example browser same-origin fetch
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const response = await fetch('/api/storage/token-images', {
  method: 'POST',
  headers: {
    'Content-Type': file.type // 'image/png', 'image/jpeg', or 'image/webp'
  },
  body: file // Raw bytes sent directly
});

const data = await response.json();
console.log(data.imageURL); // "/api/storage/token-images/<uuid>"

Success Response (200 OK)

json

{
  "imageURL": "/api/storage/token-images/123e4567-e89b-12d3-a456-426614174000"
}

Error Responses

400 Bad Request: { "error": "Token image upload is empty." } or invalid magic bytes mismatch.
403 Forbidden: { "error": "Token image uploads require the same origin." }
413 Payload Too Large: { "error": "Token image must be 4 MB or smaller." }
415 Unsupported Media Type: { "error": "Token image must be PNG, JPEG, or WebP." }
429 Too Many Requests: { "error": "The shared token image upload budget is exhausted. Please try again later." } (Includes a Retry-After header in seconds).
500 Internal Server Error: { "error": "Failed to save token image." }

GET

/api/storage/token-images/{imageId}

Retrieves previously uploaded raw image bytes by their UUID. The server streams the image directly, applies the correct Content-Type (PNG/JPEG/WebP) based on object metadata, and attaches a rigid X-Content-Type-Options: nosniff security header.

Caching: Image responses use public, max-age=31536000 (1 year). No authentication is required to view images.

bash

curl -O -J https://api.example.com/api/storage/token-images/123e4567-e89b-12d3-a456-426614174000

404 Not Found: { "error": "Token image not found." } — returned for invalid UUID strings or missing objects.
500 Internal Server Error: { "error": "Failed to serve token image." }

Architecture & Security

Persistence & Privacy

The current environment emphasizes local data testing and strict network separation.

Local Storage Isolation: All wallets, trades, generated market configurations, and portfolio states are stored entirely in the client's browser localStorage mechanism (e.g., cmc_curve_markets, cmc_curve_wallet). There is no server/database persistence. Clearing browsing data results in immediate, irreversible loss of all local preview progress.
Image Upload Privacy: Image uploads via the API are immediately public through a public access policy. UUID paths are identifiers, not a privacy boundary; viewing requires no signed URL or login. Do not upload sensitive or identifying images.
Data Rollbacks: To prevent corrupted state during a failure to write to the browser's localStorage quota limits, launch workflows perform manual rollback snapshots.

FAQ & Troubleshooting

Why is the Active Markets list empty on the homepage?

By design, the homepage shows an empty list of active markets until a real onchain deployment exists. The markets you create are intentionally sequestered to your local browser and display only in the portfolio and local commodities lists.

I uploaded an image but the server returns 403 Forbidden.

The token image upload route strictly enforces the Same-Origin Policy. If your browser sends an Origin header, it must perfectly match the Host of the API server.

Why does the Buy button reject my transaction near the end of the curve?

The buy transaction calculates the exact output using the constant product formula. The guardrails will reject any trade that attempts to output tokens pushing the distributed supply past the 800,000,000 token limit. Graduation logic is blocked; you cannot bypass this cap.

Can I test PancakeSwap integration?

No. Although the contract README references PancakeSwap V2 (not Uniswap), the migration functionality permanently reverts. No router is approved, and no liquidity pools can be minted.

Mainnet Blockers

Network connectivity · read-only

Checking BSC mainnet…

Server-side RPC access only. No wallet signing, contract deployment, or fund movement. Refreshes every minute.

The smart contracts underpinning the future platform exist as an isolated, bounded testnet foundation. They are strictly designated as non-production. Deployment commands strictly forbid mainnet execution.

PancakeSwap V2 Integration

Future targets aim for PancakeSwap V2 (not Uniswap). However, the migration logic is permanently reverted in the existing contract source. A mathematical discontinuity exists at the graduation target:

Terminal-to-V2 ratio is approximately 1.5119 (4/sqrt(7)). This creates an approximate 51.2% opening discontinuity when entering the automated market maker pool.

Currently, no router is approved, no liquidity tokens are minted, and the reserved pool of 200,000,000 tokens remains inaccessible.

Checklist Before Real Deployment

Transitioning from this local preview to active onchain status requires resolution of severe blockers:

Audit finalization: Independent security audits for all curve transitions.
Oracle governance: Reliable onchain feeds for pricing.
Legal and Compliance: Explicit backing, redemption, and synthetic peg structures.
Verification: Proof of token burns and correct holder distributions.
Migration Design: Resolution of the LP discontinuity phase.

Loading page…

PancakeSwap V2 Integration

Terminal-to-V2 ratio is approximately 1.5119 (4/sqrt(7)). This creates an approximate 51.2% opening discontinuity when entering the automated market maker pool.

Currently, no router is approved, no liquidity tokens are minted, and the reserved pool of 200,000,000 tokens remains inaccessible.

Checklist Before Real Deployment

Transitioning from this local preview to active onchain status requires resolution of severe blockers:

Audit finalization: Independent security audits for all curve transitions.
Oracle governance: Reliable onchain feeds for pricing.
Legal and Compliance: Explicit backing, redemption, and synthetic peg structures.
Verification: Proof of token burns and correct holder distributions.
Migration Design: Resolution of the LP discontinuity phase.