Stability Protocol API and Developer Resources

Read the public gold and silver price data used by Stability Protocol, check service status, or connect an agent to our published documentation. The API exposes public market-reference data. Financial values entered in the Zakat calculator stay in the browser; they are not submitted to this API.

What you can build

Display gold and silver reference prices in a supported currency.
Monitor the public service from an application or terminal.
Help an agent find calculator pages, understand the published conventions, and cite the sources.

The public API is read-only REST with JSON responses. It does not calculate an individual's Zakat, accept asset balances, or expose a public GraphQL endpoint. Use the browser calculator for an estimate and read the methodology before interpreting the result.

Quickstart

Fetch the latest available cached price response:

curl --fail-with-body https://metal-prices.stachboo.workers.dev/prices

Base URL: https://metal-prices.stachboo.workers.dev. Read the response timestamp and source before using a quote. The timestamp describes response generation, not a certified market transaction time. Validate that your currency and positive metal prices are present; a missing or unavailable quote is not a zero price.

Inspect source for fallback data. A value containing fallback-static identifies static estimates; the metalpriceapi.com fallback also uses a static silver price. These responses must not be presented as wholly live market quotes.

Authentication

No API key or account is required for the public /prices and /status endpoints. Send a GET request for JSON or HEAD for response headers without a body. Do not include credentials or personal financial information in request URLs or headers.

Browser CORS access is restricted to the site's allowed first-party and localhost origins. Other browser origins are not granted access. Command-line and server clients do not rely on browser CORS and can use the public endpoints directly.

Public endpoints and OpenAPI

Method	Endpoint	Purpose
GET / HEAD	/prices	Cached metal prices by currency, with source and timestamp.
GET / HEAD	/status	Public service health and cache configuration; no financial inputs.

Download the OpenAPI 3.1 specification for response schemas and endpoint details. The price response contains the supported currencies together; currency selection in the CLI filters that response locally.

Rate limits

The /prices policy applies an approximate limit of 60 requests per 60 seconds per IP at each Cloudflare colo (edge location), including cached responses and HEAD requests. This is not a globally coordinated account quota. Cache responses in your integration and avoid polling on every keystroke.

Price responses advertise RateLimit-Policy: "prices";q=60;w=60. On HTTP 429, RateLimit reports r=0 and Retry-After: 60 asks you to wait 60 seconds before retrying. Successful responses do not promise a remaining-request count. Add backoff and stop repeated retries when the service remains unavailable.

Errors and unavailable data

404 / NOT_FOUND: the path is not a documented public endpoint. Check the base URL and path.
405 / METHOD_NOT_ALLOWED: the method is unsupported. Use GET or HEAD for public data.
429 / RATE_LIMITED: the price-request limit was reached. Respect Retry-After.
500 / INTERNAL_ERROR: the service could not complete the price request. Retry after a short delay and check /status if the problem continues.

Public errors use application/problem+json with a machine-readable code, an explanation in detail, and a recovery hint. Check the HTTP status before reading JSON. A healthy /status response describes the service; it does not certify the freshness or availability of every currency quote. Do not turn missing values into zero.

Official downloadable CLI

Install the Stability Protocol CLI 0.1.0 package directly from this site using Node.js and npm:

npm install --global https://stabilityprotocol.space/downloads/stability-protocol-cli-0.1.0.tgz

The installed command is stability-protocol:

stability-protocol prices --currency USD
stability-protocol status
stability-protocol --help

The CLI reads the same public API. It does not require an API key or submit your asset values.

Resources for agents

Agent skills index: discover the published calculation, nisab, and calculator-directory skills with their content digests.
llms.txt: a concise entry point to calculator pages, sources, and limitations.
Sitemap: discover published canonical URLs rather than assuming every country and asset combination exists.

Verify the skill digest when consuming a skill. Read its usage conditions and limitations before applying a rule, and preserve those qualifications when giving an answer.

Safe sandbox walkthrough

Start with the CLI's deterministic offline example. It uses a fixture and makes no network request. Then check connectivity with the public status endpoint before reading service price data:

stability-protocol prices --example
curl --fail-with-body https://metal-prices.stachboo.workers.dev/status
curl --fail-with-body https://metal-prices.stachboo.workers.dev/prices

The offline example is illustrative, not a current market quote. The two curl requests are read-only calls to the public service. No test account, API key, payment, or financial balance is needed. Keep real account and asset information on your own device.

Attribution and citation

When displaying a price, identify Stability Protocol as the service, retain the response's source and timestamp, and link to this documentation. When explaining a religious rule, cite the relevant passage in the sources and methodology or a published guide. Distinguish a cached market reference from a religious ruling and describe the calculator's result as an estimate.

For integration problems or documentation corrections, contact the project with the endpoint, HTTP status, and a minimal example without secrets or personal financial data. This developer portal is available in English.