API documentation
Manage account API keys and check integration access when the access-check service is enabled. This reference explains the supported scope, authentication and current limits.
Available capabilities
- Create, list and revoke account API keys from the dashboard.
- Manage the account IP allowlist and view API activity and request limits.
- Authenticate a key with
GET /integration/accesswhen access checks are enabled. - Save webhook configurations; outbound webhook delivery is unavailable.
Access-check keys validate access only. Order keys with quote, create and read scopes support single orders when order execution is enabled. Mass ordering is available in the dashboard; API keys do not permit mass orders, Cart or payments.
Authentication and base URL
Use the API base URL supplied for your SMMViva environment. The default path prefix is /api/v1; all paths below are relative to that base. In these examples, API_BASE_URL includes the prefix and has no trailing slash.
For integration endpoints, send your key in the X-API-Key header. Create a key in API key management and save the full value when it is generated. Keep it on your server, outside browser code, shared URLs and source control. Revoke a key if it is exposed.
X-API-Key: <your-api-key>Account management routes use your signed-in session with Bearer authentication. An API key does not grant access to those routes. To inspect the enabled scope, use GET /api-keys/capabilities with an account session token:
curl --request GET "$API_BASE_URL/api-keys/capabilities" --header "Authorization: Bearer $SMMVIVA_SESSION_TOKEN"The capabilities response reports access_check_enabled, authentication: "X-API-Key" and scope: "access-check-only". order_execution reports whether scoped order execution is enabled; payment_execution and webhook_delivery remain false. Creating a key does not enable the access-check service.
Check API access
GET /integration/access accepts no request body. The account and key must be active. When the account IP allowlist contains entries, the calling IP must match an allowed address or network.
curl --request GET "$API_BASE_URL/integration/access" --header "X-API-Key: $SMMVIVA_API_KEY"Example successful response for a key with a limit of 60 requests and no saved IP restrictions:
{
"authenticated": true,
"key_prefix": "<your-key-prefix>",
"scope": "access-check-only",
"rate_limit": 60,
"remaining": 59,
"window_seconds": 60,
"ip_restricted": false
}Accepted checks consume the key’s rolling 60-second request allowance and appear in API activity. The default key allowance is 60; use the returned limit for your key. Responses include RateLimit-Limit, RateLimit-Remaining and RateLimit-Policy. A quota rejection includes Retry-After in seconds. Access-check responses use Cache-Control: no-store.
Orders
Create an order key using Create order key in Dashboard > API. Choose quote, create and read permissions and an expiry of 7, 30 or 90 days. Save the raw key when shown; it is displayed once. Keep it on your server.
All paths below are relative to /api/v1. Use only X-API-Key. Sending an Authorization header or cookies with order integration requests returns 400: Use only X-API-Key for this integration.
POST /integration/orders/quoterequires the quote scope.POST /integration/ordersrequires the create scope and anIdempotency-Keyheader: 8–128 characters using letters, digits, period, underscore, tilde or hyphen.GET /integration/orders/{id}requires the read scope and returns your own order.
Read the public catalog and select a service and an orderable offer from GET /catalog/{serviceId}/offers. Use that offer’s id as offerId only when is_orderable is true. The request contains serviceId (positive integer), offerId, link and quantity (positive integer), with optional comments and quoteToken. Use the exact selected offer’s target and quantity limits.
The example below expects API_BASE_URL (including /api/v1), SMMVIVA_API_KEY, SERVICE_ID, OFFER_ID, ORDER_TARGET and QUANTITY from your selected public offer. ORDER_TARGET must be a valid URL; the printf example assumes it contains no quotes or backslashes. Do not send account, wallet or other private fields.
printf '{"serviceId":%s,"offerId":"%s","link":"%s","quantity":%s}' "$SERVICE_ID" "$OFFER_ID" "$ORDER_TARGET" "$QUANTITY" > order-request.json
curl --request POST "$API_BASE_URL/integration/orders/quote" \
--header "X-API-Key: $SMMVIVA_API_KEY" \
--header "Content-Type: application/json" --data @order-request.jsonThe quote response includes offerId, serviceId, total_cost, price_per_1000, min_quantity, max_quantity, expires_at, quoteToken, currency and fx details. Keep decimal monetary strings exact. Review the current quote and add its quoteToken to order-request.json before creating the same order.
curl --request POST "$API_BASE_URL/integration/orders" \
--header "X-API-Key: $SMMVIVA_API_KEY" \
--header "Idempotency-Key: $ORDER_KEY" \
--header "Content-Type: application/json" --data @order-request.json
curl --request GET "$API_BASE_URL/integration/orders/$ORDER_ID" \
--header "X-API-Key: $SMMVIVA_API_KEY"Choose a unique valid ORDER_KEY for each intended order. Retain the same key and unchanged request when recovering an uncertain submission; never create a new key just because a response was lost. ORDER_ID is the accepted order’s id.
- 401: invalid, expired or insufficiently scoped key.
- 403:
API client address is not allowed, when the account IP list is nonempty and excludes the client address. - 429:
API order request limit reached; followretry_after_seconds. - 503:
API order execution is not enabled, or the service’s maintenance response.
Responses and errors
| Status | Meaning | Next step |
|---|---|---|
| 200 | Access authenticated | The key passed the account, IP and request-limit checks. This does not authorize order or payment execution. |
| 401 | Invalid API access | Check the key and whether the account and key are active. Send the key in the X-API-Key header. |
| 403 | Client IP is not allowed | Check the account IP allowlist against the public IP used by your application. |
| 429 | Request limit reached | Wait for the Retry-After period before retrying. Avoid immediate repeated requests. |
| 503 | Access checks unavailable | Access checks are disabled, or the key limit needs review. Check account capabilities or contact support. |
Account management requests require a valid signed-in session. The service also applies a general request throttle, so pace requests and follow any retry guidance in the response.
Manage your integration
Sign in to manage these settings for your own account:
- API keys — generate a key, review existing keys or revoke access.
- IP allowlist — add or remove IPv4, IPv6 or CIDR entries. Entries apply to all keys on the account.
- API activity — review recorded requests and filter by endpoint.
- Request limits — review the allowance for your keys.
- Webhook configurations — save or remove configurations for future delivery support.
Webhooks and ordering
Webhook configuration accepts an HTTPS URL and events selected from order.completed, order.partial, order.cancelled and deposit.confirmed. order.cancelled is sent when an order is cancelled, including an order that could not be completed and was returned to your wallet. It carries the order ID and status only. New configurations are saved inactive. A secret is returned once on creation; store it securely.
Webhook delivery is unavailable. Saved configurations do not send events. Webhook capabilities report configuration: true and delivery: false; the test action returns an unavailable or disabled error. There is no delivery payload or signature verification contract to implement yet.
Order-scoped keys use the single-order endpoints above. Mass orders use the signed-in dashboard at /dashboard/mass-order. API keys do not permit mass orders, Cart or payments.
For access questions, contact support with the endpoint and response status. Keep full API keys and session tokens out of support messages.
