SMM Panel API Documentation: API v1 vs API v2, and Which One to Integrate

Orbismm's SMM panel API documentation covers two APIs. API v2 is the standard SMM panel API: one URL, form fields key and action, and it works with any panel script that supports providers. API v1 is REST and JSON with scoped bearer keys, idempotency keys, batch orders and signed webhooks. Use v2 for scripts, v1 for code you write.

Both APIs run on the same account, the same balance and the same orders, so choosing one doesn't lock you out of the other. This guide compares them point by point, based on how the endpoints actually behave, and explains the three v1 features that matter most in production: idempotency, batch orders and signed webhooks.

What is in the Orbismm API documentation?

How do API v1 and API v2 compare?

When should you use API v2?

• You run a panel script and want to add Orbismm as a provider. v2 is the format those scripts already speak, so setup is a URL and a key.
• You have existing code written for another provider's standard API and want to reuse it unchanged.
• Your needs are simple: list services, place orders, check status, request refills and cancel.

The main thing to watch is retries. Because v2 has no duplicate protection, a script that resends add after a timeout can place two orders. Check your script's retry behaviour before going live.

When should you use API v1?

• You are writing your own integration, such as a storefront, a bot or an internal tool, and want clear HTTP status codes and stable error codes to branch on.
• Orders are created by automated jobs where a network timeout must never produce a duplicate.
• You place many orders at once and want one request instead of many.
• You want order and refill changes pushed to your server instead of polling.
• You want keys limited to what a tool needs, such as a reporting dashboard that can read but never order.

How do scopes and key settings protect you?

Every key carries one or more scopes, and both APIs check them. In v2, services, status, refill_status and balance need read, while add, refill and cancel need orders; a key without it gets This API key is not allowed to do that. In v1, a request outside the key's scopes returns 403 missing_scope, and everything under /v1/webhooks needs the webhooks scope. A key can also be limited to an IP allowlist, so a leaked key is useless from any other server.

How does idempotency work in API v1?

A request can time out after the order was already placed. With an Idempotency-Key header on POST /v1/orders, a retry can't create a second order:

• First request: the order is placed and the answer is 201.
• Same key, same request: you get the original order back with 200 and the header Idempotent-Replayed: true. Nothing is charged again.
• Same key, different request (another service, link or quantity, for example): 409 idempotency_conflict.
• Use a new key, such as a UUID, for every new order. In a batch, each item carries its own idempotency_key.

How do batch orders and webhooks work?

POST /v1/orders/batch takes a list of orders in one request. Each item succeeds or fails on its own, and the answer lists a result per item with its index, so one bad link doesn't block the rest. Batch size limits are in the reference.

Webhooks push events to an HTTPS endpoint you register: order.status_changed, order.started, order.completed, order.partial, order.canceled, refill.completed, refill.rejected, service.changed and balance.low. Price increases are announced at least 48 hours ahead in the panel and by webhook, so an integration can adjust its own prices in time.

• Each request carries an Orbismm-Signature header in the form t=<unix time>,v1=<signature>, where the signature is a hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your endpoint secret.
• Recompute it over the raw body before parsing, compare in constant time, and reject stale timestamps.
• Endpoints can be tested with a test event and their secret can be rotated through the API.
• Sandbox endpoints receive sandbox events, signed the same way and marked livemode: false.

Can you use both APIs at once?

Yes. They share the account, balance and orders, so a common setup is a panel script placing orders through v2 while a small service subscribes to v1 webhooks for alerts on partial orders, rejected refills and low balance. Give each part its own key with only the scopes it needs, and test both with sandbox keys first. SMM panel API testing with a sandbox has a full test plan.