Build with the Peryn API

01Quickstart#

Three steps to your first answer.

1. Войти with your email and add credit under Add credits.
2. Create a key under API keys. It is shown once; we store only a hash of it. Keep it in the PERYN_API_KEY environment variable.
3. Point any OpenAI SDK at the base URL and send a request.

curl https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct","max_tokens": 64,"messages": [{"role": "user", "content": "Say hello in five words."}]}'

The answer has the OpenAI shape, with the token counts you pay for in usage:

{"id": "chatcmpl-…","object": "chat.completion","created": 1791216000,"model": "llama-3.1-8b-instruct","choices": [{"index": 0,"message": { "role": "assistant", "content": "Hello. Nice to meet you." },"logprobs": null,"finish_reason": "stop"}],"usage": { "prompt_tokens": 16, "completion_tokens": 8, "total_tokens": 24 }}

02Base URL and models#

One base URL for every endpoint. Send your key as a Bearer token.

https://api.peryn.ai/v1

Every request that runs a model needs the header Authorization: Bearer <key>. Production keys start with pc_live_. Bodies are JSON, up to 2 MB.

curl https://api.peryn.ai/v1/models

Request fields

The fields below are read; other OpenAI fields that do not change the answer (such as user or metadata) are ignored.

Models take text in and give text out. Images and other non-text content, n or best_of other than 1, echo, suffix, token-id prompts, more than one prompt per request, and the older functions and function_call fields (use tools and tool_choice) are answered with a 400 that names the field. If you need one of them, talk to us. Each model lists the optional fields it supports in supported_parameters on GET /v1/models.

Tool calling

The API takes tools, tool_choice, parallel_tool_calls and messages with role tool in the OpenAI format and passes them to the model. No model in this release declares tool calling. A model that does not declare it may refuse the request: tool_choice auto, the default when you send tools, is answered with a 400, code bad_request, and the model’s reason.

Structured outputs

response_format takes type json_object or json_schema. We check a json_schema before the request runs: one we cannot use is answered with a 400 before any token is generated. We also check every answer that is not streamed: if it is not valid JSON, or does not match your schema, you get 502 invalid_output instead, and nothing is billed (output_check_failed when the check could not finish in time). An answer cut off by max_tokens comes back as it is, with finish_reason length. Streamed answers are not checked. No model in this release declares structured outputs.

Log probabilities

logprobs and top_logprobs are passed to the model, and what it returns comes back in each choice’s logprobs. No model in this release declares them.

Text completions

curl https://api.peryn.ai/v1/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct", "prompt": "The capital of France is", "max_tokens": 16}'

Response headers

• x-request-id and Inference-Id on every response: answers, errors and streams alike, including a 503 while the gateway restarts. Both carry the same value, starting with req_. It is the id your request, its token counts and its cost are recorded under.
• x-pc-node-country on every response a GPU node served, streamed or not: the node’s country as a two-letter code (ISO 3166-1).

Keep the request id with your own logs, and quote it when you write to us about a request. We store no prompts or answers, so the id is how we find it. On an error, the OpenAI SDKs give it as request_id (Python) and requestID (JavaScript); the sample under Ошибки prints it.

curl -sS -D - -o /dev/null https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct", "max_tokens": 8, "messages": [{"role": "user", "content": "Hi"}]}'

03Streaming#

Server-sent events in the OpenAI format: tokens arrive as the model writes them.

Set stream: true. Each event is a data: line with a chat.completion.chunk; the text is in choices[0].delta.content and a final chunk carries finish_reason. With stream_options: {"include_usage": true} every chunk has "usage": null and one more chunk, with empty choices, carries the token counts. The stream ends with data: [DONE].

curl -N https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct","max_tokens": 128,"stream": true,"stream_options": {"include_usage": true},"messages": [{"role": "user", "content": "Write a haiku about GPUs."}]}'

: ping
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1791216000,"model":"llama-3.1-8b-instruct","choices":[{"index":0,"delta":{"role":"assistant","content":"Silicon"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {…,"choices":[{"index":0,"delta":{"content":" hums"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {…,"choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}
data: {…,"choices":[],"usage":{"prompt_tokens":16,"completion_tokens":19,"total_tokens":35}}
data: [DONE]

• Lines that start with a colon (: ping) keep the connection open while the model works on its first token. The OpenAI SDKs skip them.
• An error before the first event comes back as a normal HTTP error. An error after the stream has started arrives as an event: error line with the error JSON, then data: [DONE].
• If the stream breaks or you close it, you pay for the tokens that reached you and nothing more. If none did, you pay nothing.
• If no GPU is serving the model, a streamed request waits too, and sends nothing until a GPU takes it (see When GPUs are busy).

04Models and prices#

Live prices in US dollars per million tokens, excluding VAT.

Put the model id in the model field. These are our Standard prices, per model, 30% below market. They can change; a request pays the price in force when it starts.

• llama-3.1-8b-instructAvailable

  Llama 3.1 8B Instruct · 8B · 32,768 tokens, max output 8,192

  Input

  $0.014

  Output

  $0.028

The same table is JSON at https://app.peryn.ai/api/pricing and, with context lengths, at GET /v1/catalog. The same prices are on the pricing page; every model’s licence is on the licences page.

curl https://api.peryn.ai/v1/catalog

What a request costs

Input tokens times the input price plus output tokens times the output price, rounded up to the next millionth of a dollar. We count the tokens ourselves with the model’s own tokenizer; the counts are the usage in every answer and on your usage page.

05Privacy tiers#

New keys use the Standard tier. Private is on request: talk to us.

Standard

No training on prompts or completions, ever. Zero retention: we do not log or store prompt or completion content; we keep only request metadata (such as request ID, account, timestamps, model, token counts, latency, cost and status) for billing and reliability. Standard runs on GPUs that also mine $PEARL; Mining and your data in the privacy policy explains what that means. The prices above are Standard prices.

Where your requests run

By default, a request runs on any healthy node, in any country. Set a region rule for your whole account under Настройки. Narrow it for one key on the API keys page. A rule is EU only, US only, US + EU, your own list of countries, or countries to exclude. Requests then run only on nodes in the allowed countries. If those nodes are all busy, the request gets 429 no_capacity. If none of them serves the model, it is held as described under When GPUs are busy, then fails with 503 and code no_capacity_in_region. It never runs elsewhere instead.

A node’s country comes from its operator’s declaration, checked against the location of its IP address. A dishonest operator could fake both (for example with a VPN); we remove nodes we catch. Each answer names its node’s country in x-pc-node-country, and your usage page breaks your requests down by country.

06Rate limits and credits#

Per-key limits per minute, and prepaid credit in US dollars.

Rate limits

• Each key allows 60 requests and 200,000 tokens per minute. Both refill continuously. The API keys page shows each key’s limits. Need more? Talk to us.
• A request counts its input tokens plus max_tokens against the token limit when it starts. When it ends, it gets back what it didn’t use. Without max_tokens it counts the model’s full output allowance (up to 8,192 tokens), so setting it lets more requests run.
• Over a limit, the request is refused at once with 429, code rate_limit_exceeded, and a Retry-After header in seconds. Nothing is queued; wait that long and retry.
• When every GPU for a model is busy, the request is refused at once with 429, code no_capacity, and a Retry-After header, rather than waiting in a queue.

Credits

• Credit is prepaid in US dollars, excluding VAT. Pay with stablecoins: your account’s own deposit address on Base, Arbitrum or Ethereum is under Add credits, with the token to send, once you accept the customer terms. A deposit is credited dollar for dollar once its block is final. Deposits under $1 are held until your held deposits reach $1. Send only that token, on those networks: anything else is not credited automatically.
• When a request starts we hold its worst case: input tokens plus max_tokens at the model’s price. When it ends we charge what it used and release the rest. If your available credit can’t cover the hold, the request is refused with 402, code insufficient_quota.
• A request that fails before any token reaches you costs nothing.
• The usage page shows requests, tokens and cost per key, model and country, for the last 7, 30 or 90 days.
• Unused credit expires after 12 months without activity (a sign-in, a request or a purchase). We email you at least 30 days before.

07Ошибки#

Errors use the OpenAI shape, so the OpenAI SDKs raise them as exceptions with the status code.

Errors that can clear by themselves (429, 503) carry a Retry-After header.

curl -i https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "no-such-model", "messages": [{"role": "user", "content": "Hi"}]}'

Retry 429, 500, 502, 503 and 504 with backoff; the OpenAI SDKs do this for you (twice by default). Fix the request for the other codes. Stuck? Write to hello@peryn.ai with the request id from x-request-id or Inference-Id.

08Майнинг с Peryn#

Mine Pearl through our pool.

Set up your machine

Run our agent on any Linux machine with an NVIDIA GPU. No account: the $PEARL address in the command is where we pay.

curl -fsSL https://peryn.ai/install | sh -s -- YOUR_PEARL_ADDRESS

• It asks for sudo, installs our agent as a service, and updates itself.
• Needs NVIDIA driver 580 or newer for Blackwell datacenter, RTX PRO and RTX 50; 570 or newer for Hopper; 550 or newer for RTX 40, RTX 30, RTX Ada, Ada datacenter, RTX Ampere, Ampere datacenter and Turing.
• On HiveOS, a flight sheet runs our agent on every rig: Mine with HiveOS. HiveOS ships NVIDIA driver 550, which can’t run RTX 50 or RTX PRO Blackwell cards. On those rigs, update to 580 or newer first: nvidia-driver-update 580.178.04 && reboot.
• To join an account instead, put a fleet key from the miner portal in place of the address.

Нужен кошелёк? → Pearl Safe (откроется в новой вкладке)

Выплаты

• Условия — в правилах нашего пула.
• A block reward is credited after 100 confirmations. A block that leaves the chain before that pays nothing, and its credit is removed.
• Выплата на ваш адрес $PEARL (каждые 2 часа), когда начислено от 1 $PEARL. Less stays owed and is paid in a later batch; nothing is lost.
• Every payout is screened against sanctions lists before it is sent.

Fees and payout schemes

PPS+

1%

A fixed payment for every share, plus transaction fees. No luck involved. The default.

PPLNS

1%

Paid from the blocks the pool finds. Choose it with mode=pplns in the rig’s password.

Founding Miners

0% PPLNS / 0.5% PPS+

0% on PPLNS until Pearl’s FP8 upgrade and for 6 months after it.

GPU Clouds accounts pay the Duplex fee: 2% of the $PEARL their enrolled machines mine, in place of the pool fee, and no other fees. It doesn’t stack with the Founding Miner terms: their other mining keeps the Founding rate.

With PPLNS, when the pool finds a block, the whole reward is split among the shares in the last stretch of work: the latest accepted shares whose difficulty adds up to twice the network difficulty. Your part is your shares’ difficulty in that stretch. A share counts towards every block found while it is in the stretch, so steady mining is paid steadily, and joining only when the pool looks lucky gains nothing.

Your dashboard

Look up your $PEARL address to see its hashrate, accepted and rejected shares, $PEARL estimated, owed and paid, and each worker. No sign-in. Look up your address.

Нужен кошелёк? → Pearl Safe (откроется в новой вкладке)

Running a fleet? Tell us about your fleet. See the network mine and serve on peryn.ai/live.

Troubleshooting

Rejected shares show on your dashboard by reason. What each one means:

21 Stale share (job expired: new block)

Новый блок пришёл раньше, чем шара дошла до пула. Несколько на сотню — норма. Больше — признак медленной связи: используйте ближайший к вам TLS-порт или проводное подключение.

21 Stale share (job not found)

Шара относилась к заданию, которое это подключение не получало или которое давно заменено. Перезапустите майнер, чтобы он взял свежие задания. Если повторяется, проверьте, что подключение использует только один процесс майнера.

22 Duplicate share

Одно и то же доказательство отправлено дважды. Обычно это повтор майнера после потерянного ответа. Проверьте сеть между ригом и пулом.

22 Duplicate share (already credited, sent again in other bytes)

Уже засчитанная пулом шара отправлена повторно в другой кодировке. Честный повтор отправляет те же байты. Обновите майнер: такие шары учитываются для бана.

23 Low difficulty share

Сложность шары ниже той, что запросил пул. Уберите d=N из пароля или увеличьте значение. Обновите майнер, если он игнорирует сложность задания.

23 Low difficulty share (rank penalty)

Шара прошла обычный таргет, но не штраф Pearl за её ранг шума. Обновите майнер до версии, которая учитывает штраф за ранг. Такие отклонения никогда не ведут к бану.

20 Invalid proof

Верификатор Pearl отклонил доказательство. Часто это нестабильный разгон или ошибки памяти. Снизьте частоты, обновите драйвер, затем майнер.

20 Invalid proof: decode

Не удалось прочитать доказательство. Обновите майнер. Проверьте, что он настроен на Pearl.

20 Invalid proof: rank

Доказательство использует ранг шума, который сеть не принимает. Используйте настройки майнера для Pearl по умолчанию.

24 Unauthorized worker (banned)

Это подключение отправило слишком много невалидных шар и временно приостановлено. Устраните причину невалидных шар; пауза закончится сама.

Using WildRig? Its pearlhash mode only works with pearlhash.xyz. On Peryn Pool use MH-Miner, SRBMiner, BzMiner, OneZeroMiner or Peryn’s own miner.

09For GPU owners#

Your GPU can serve these requests and mine $PEARL.

At launch, nodes mine only: no AI requests, no 50 GB disk check and no model downloads. The serving steps below apply once serving opens.

Your GPU mines $PEARL through our pool and serves requests. Our miner image runs the model and our node software, which never logs or stores prompts or completions. Running a fleet? Tell us about your fleet.

What you need

• An NVIDIA Hopper or Blackwell GPU (x86_64 or arm64).
• NVIDIA driver r580 or newer (CUDA 13).
• A container with 16 GB of shared memory, and disk for our image and the model weights.
• Outbound HTTPS and WebSocket only. No inbound ports: the node dials out to us.

Connect a node

1. Sign in to the miner portal and choose Add a node. Give it a name, its country and a model. You get an enrolment token: single use, valid for 24 hours.
2. Run the command the portal shows, with the image reference we send you, on RunPod, Vast.ai or your own server. The node enrols and connects to our gateway and our pool. Ask us for the image reference: tell us about your fleet.
3. The node mines from the start. Customer requests start once we approve it: we check who you are, its test requests and its country.
4. Add your payout address under Выплаты: a $PEARL address on Pearl. $PEARL you earn stays owed until you add one.

   Нужен кошелёк? → Pearl Safe (откроется в новой вкладке)

To mine without serving API requests, tick Pool only (no API traffic) when you create the token. The node then earns $PEARL only and needs no approval.

Условия — в правилах нашего пула. A block reward counts after 100 confirmations. The payout rules are under Выплаты; $PEARL estimates are on the GPU clouds page.

10Pool API#

Public JSON for pool-listing sites: the pool, its blocks, its payments and one address.

Base URL: https://app.peryn.ai/api/v1. GET only, no key, from any origin. Every answer carries "v": 1.

Amounts are $PEARL as strings with 8 decimals ("2.50000000"), hashrates are numbers in MAC/s (the unit field), and times are ISO 8601 in UTC.

Caching and limits

Answers may be cached for 60 seconds (Cache-Control: public, max-age=60); the server computes each one at most once a minute. Up to 60 requests a minute per IP address, then 429 with Retry-After. /miner/{address} shares the address dashboard’s limit (60 a minute per network) and is recomputed at most every 15 seconds per address.

{"v": 1,"name": "Peryn Pool","coin": "PRL","algorithm": "pearlhash","network": "mainnet","unit": "MAC/s","fees": {"pplns": {"open": true,"feePct": 1},"fpps": {"open": true,"feePct": 1},"founding": "Founding Miners Season 1: 0% on PPLNS until Pearl’s FP8 upgrade and for 6 months after it; 0.5% on PPS+."},"payouts": {"minimumPrl": "1.00000000","schedule": "every 2 hours","coinbaseMaturityBlocks": 100},"stratum": [{"region": "eu","label": "Europe","location": "Frankfurt","host": "pool.peryn.ai","tcpPort": 3333,"tlsPort": 3443,"status": "up"}],"pool": {"hashrate10m": 59000000000000000,"hashrate24h": 56000000000000000,"miners": 165,"workers": 180,"blocksFound": 412,"lastBlock": {"height": 131204,"time": "2026-11-02T12:00:00.000Z"}},"networkStats": {"hashrate": 410000000000000000,"difficulty": 12000000,"height": 131260},"updatedAt": "2026-11-02T12:00:00.000Z"}

{"v": 1,"network": "mainnet","blocks": [{"height": 131204,"hash": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","time": "2026-11-02T12:00:00.000Z","rewardPrl": "50.00000000","status": "pending","confirmations": 56}],"updatedAt": "2026-11-02T12:00:00.000Z"}

{"v": 1,"network": "mainnet","payments": [{"time": "2026-11-02T12:00:00.000Z","totalPrl": "1834.25000000","payees": 96,"txids": ["3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f"],"networkFeePrl": "0.00042250","networkFeePaidBy": "pool"}],"next": null,"updatedAt": "2026-11-02T12:00:00.000Z"}

{"v": 1,"address": "prl1p…","network": "mainnet","unit": "MAC/s","hashrate1h": 310000000000000,"hashrate24h": 290000000000000,"workersOnline": 1,"workersOffline": 0,"workers": [{"name": "rig01","online": true,"hashrate1h": 310000000000000,"hashrate24h": 290000000000000,"lastShare": "2026-11-02T12:00:00.000Z"}],"balance": {"owedPrl": "0.42000000","pendingPrl": "3.10000000","paidPrl": "25.00000000"},"payouts": [{"time": "2026-11-02T12:00:00.000Z","amountPrl": "2.50000000","status": "sent","txids": ["3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f"]}],"updatedAt": "2026-11-02T12:00:00.000Z"}