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.

REST / JSONWebSocket streamAPI keysFreshness status

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.

GET/v1/pricesReturn the current price snapshot.
GET/v1/prices/{symbol}Return one canonical symbol.
GET/v1/symbolsList the symbols available to your account.
GET/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/ready

04 / 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":"..."}
HTTPCodeMeaning
400websocket_requiredThe request was not a WebSocket upgrade.
403websocket_not_includedYour plan has no WebSocket connections (Starter).
403ip_not_allowedThe address is not on your IP whitelist.
429websocket_connection_limitAll 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.

HTTPCodeMeaning
401api_key_required / invalid_api_keyAuthentication is missing or invalid.
403revoked_api_key / inactive_client / ip_not_allowedThe key or account is disabled, or the address is not whitelisted.
404unknown_symbolThe symbol is not available.
429rate_limit_exceeded / monthly_quota_exceededSlow down or upgrade the plan.
503price_feed_emptyThe upstream snapshot is not ready.
X-API-Version
X-RateLimit-Remaining
X-Quota-Remaining

08 / Plans

Choose the volume your product needs.

PlanMonthly requestsPer-minute limitWebSocket connectionsAllowed IPsMonthly / yearly
Starter200,00060-1$12.99 / $129.90
Pro1,000,00018024$24.99 / $249.90
Business5,000,0006001010$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.