PIXCHARP / API DOCUMENTATION
Live price data, ready for your product.
Use one secure REST API, or a WebSocket stream, to bring the current Harem Altın price snapshot into your e-commerce experience, mobile app, internal tool, or notification workflow.
01 / Quick start
Make your first request.
Create a plan from Pixcharp, open your customer dashboard, and generate an API key. Keep the raw key on your server and send it with every request.
curl https://api.pixcharp.com/v1/prices \
-H "X-API-Key: pxa_live_your_key"02 / Authentication
Keep the key server-side.
Use either X-API-Key or a Bearer token. Do not expose your key in browser bundles, mobile binaries, screenshots, or logs.
Header
X-API-Key: pxa_live_...
Bearer
Authorization: Bearer pxa_live_...
Format
pxa_live_...
03 / Endpoints
Small surface area. Clear responses.
The first version is intentionally focused on the current snapshot, symbol discovery, and feed health.
/v1/pricesReturn the current price snapshot./v1/prices/{symbol}Return one canonical symbol./v1/symbolsList the symbols available to your account./v1/statusCheck feed freshness and snapshot status.const response = await fetch(
"https://api.pixcharp.com/v1/prices/HAS",
{ headers: { "X-API-Key": process.env.PIXCHARP_API_KEY } }
);
const price = await response.json();import os
import requests
response = requests.get(
"https://api.pixcharp.com/v1/status",
headers={"X-API-Key": os.environ["PIXCHARP_API_KEY"]},
)
print(response.json())$client = curl_init("https://api.pixcharp.com/v1/prices");
curl_setopt_array($client, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("PIXCHARP_API_KEY")],
]);
$prices = json_decode(curl_exec($client), true);GET https://api.pixcharp.com/health/live
GET https://api.pixcharp.com/health/ready04 / WebSocket stream
Prices pushed the moment they change.
Pro and Business plans can open a plain WebSocket to wss://api.pixcharp.com/v1/stream. Authenticate with the same API key as REST. You get a full snapshot on connect, then one message per price change. Stream messages do not count toward your monthly request quota; the connection handshake counts toward the per-minute limit.
import WebSocket from "ws";
const ws = new WebSocket("wss://api.pixcharp.com/v1/stream", {
headers: { "X-API-Key": process.env.PIXCHARP_API_KEY },
});
ws.on("open", () => {
// Optional: only the symbols you need. [] or ["*"] restores all.
ws.send(JSON.stringify({ type: "subscribe", symbols: ["HAS", "USDTRY"] }));
});
ws.on("message", (raw) => {
const message = JSON.parse(raw.toString());
if (message.type === "snapshot") console.log(message.data.length, "symbols");
if (message.type === "price") console.log(message.data.symbol, message.data.satis);
});// Browsers cannot set WebSocket headers, so the key goes in the URL.
// Use a dedicated key and an IP whitelist; prefer the header from servers.
const ws = new WebSocket(
"wss://api.pixcharp.com/v1/stream?apiKey=" + encodeURIComponent(key)
);// On connect, and again after "subscribe"
{"type":"snapshot","asOfUtc":"2026-11-14T10:24:13Z","market":"open","data":[{"symbol":"HAS","alis":6127.46,"satis":6155.99,...}]}
// Every time a price changes
{"type":"price","data":{"symbol":"USDTRY","alis":41.1,"satis":41.2,"asOfUtc":"2026-11-14T10:24:14Z","source":"harem","stale":false}}
// Every 30 seconds (no reply needed)
{"type":"ping","ts":"2026-11-14T10:24:43Z"}
// A bad client message; the connection stays open
{"type":"error","code":"invalid_symbol","message":"..."}| HTTP | Code | Meaning |
|---|---|---|
| 400 | websocket_required | The request was not a WebSocket upgrade. |
| 403 | websocket_not_included | Your plan has no WebSocket connections (Starter). |
| 403 | ip_not_allowed | The address is not on your IP whitelist. |
| 429 | websocket_connection_limit | All connections of your plan are open. Connections from all keys count together. |
Open connections are re-checked every 60 seconds. If the key is revoked, the plan changes or the address leaves the whitelist, the server sends an error message and closes with code 1008. Reconnect with backoff after any close.
05 / IP whitelist
Lock your keys to your servers.
Add your server addresses in the customer dashboard. While the list is empty, every address is accepted. Once it has entries, REST and WebSocket calls from any other address get 403 ip_not_allowed, and those calls do not use your quota. Single IPv4 and IPv6 addresses and CIDR ranges are accepted; Starter allows 1 entry, Pro 4 and Business 10.
{
"title": "ip_not_allowed",
"status": 403,
"detail": "Requests from 198.51.100.9 are not allowed for this API client. Add the address to the allowed IP list."
}The detail shows the address the API saw, which is the one to add when you are unsure of your server's outbound IP.
06 / Responses
A predictable JSON shape.
{
"version": "v1",
"asOfUtc": "2026-08-05T10:24:13Z",
"source": "harem",
"stale": false,
"data": [
{
"symbol": "HAS",
"alis": 6127.46,
"satis": 6155.99,
"kapanis": null,
"acilis": null,
"asOfUtc": "2026-08-05T10:24:13Z",
"source": "harem",
"stale": false
}
]
}07 / Errors and limits
Useful limits, visible in headers.
Successful and throttled responses expose the API version, rate limit, and monthly quota state when available.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | api_key_required / invalid_api_key | Authentication is missing or invalid. |
| 403 | revoked_api_key / inactive_client / ip_not_allowed | The key or account is disabled, or the address is not whitelisted. |
| 404 | unknown_symbol | The symbol is not available. |
| 429 | rate_limit_exceeded / monthly_quota_exceeded | Slow down or upgrade the plan. |
| 503 | price_feed_empty | The upstream snapshot is not ready. |
08 / Plans
Choose the volume your product needs.
| Plan | Monthly requests | Per-minute limit | WebSocket connections | Allowed IPs | Monthly / yearly |
|---|---|---|---|---|---|
| Starter | 200,000 | 60 | - | 1 | $12.99 / $129.90 |
| Pro | 1,000,000 | 180 | 2 | 4 | $24.99 / $249.90 |
| Business | 5,000,000 | 600 | 10 | 10 | $59.99 / $599.90 |
The demo plan is reserved for internal testing. Public customers receive Starter, Pro, or Business limits from the backend provisioning flow.