REST-API v2

Überblick

Das ist die Oberfläche, die ein KI-Agent steuert. Jeder Aufruf ist ein Verb, gewählt über action, sodass ein Agent den Katalog durchsucht, Rate und Limits zurückliest und dann handelt – Suchen-dann-Handeln, mit dem Preis bestätigt, bevor Geld bewegt wird. Der MCP-Server und die CLI kapseln genau diese Aufrufe; diese Seite zeigt das rohe Protokoll darunter.

Die API folgt der weit verbreiteten SMM API v2-Form, sodass bestehende Panel-Software, Skripte und Agenten-Integrationen mit minimalen Änderungen funktionieren. Jede Operation läuft über einen einzigen Endpunkt und wählt das Verb mit dem Parameter action. Antworten sind JSON. Leicht für ein Skript oder ein LLM zu parsen und zu verketten.

Endpunkt

POST https://api.socialgo.com/api/v2

Authentifizierung

Die Auth erfolgt pro Anfrage – keine Session, kein Handshake, und genau das macht sie für einen Agenten aufrufbar. Sende deinen geheimen key bei jedem Aufruf. Finde und rotiere ihn im Dashboard unter Konto → API. Behandle den Schlüssel wie ein Passwort: Halte ihn serverseitig, niemals im Client-Code oder in einem Agenten-Prompt.

Anfrageformat

Sende application/x-www-form-urlencoded-Formularparameter per POST. Jede Antwort ist JSON. Zwei Parameter sind bei jedem Aufruf dabei:

• key: dein API-Schlüssel (erforderlich)
• action: das auszuführende Verb (erforderlich)

Fehlerformat

Bei einem Fehlschlag enthält die Antwort ein error-Feld mit einer menschenlesbaren Meldung, und der HTTP-Status spiegelt das Problem wider (z. B. 400 ungültige Anfrage, 401 ungültiger Schlüssel). Eine vorhersehbare Form, sodass ein Skript oder Agent darauf verzweigen kann, ohne zu raten.

{
  "error": "Incorrect request"
}

Aktionen

Jedes Verb erledigt eine Aufgabe. Ein Agent verkettet sie in Reihenfolge: services, um zu finden, was er kaufen soll, add, um es zu kaufen, status, um es zu verfolgen. Die Leseaufrufe (services, status, balance) lassen ihn Preis und Guthaben bestätigen, bevor die Schreibaufrufe (add, refill, cancel) etwas ausgeben.

1. Dienste auflisten

Der Katalog, den ein Agent zuerst liest: jeder Dienst, den er bestellen kann, mit Dienst-ID, Kategorie, Rate (Preis pro 1000) und Min./Max.-Mengen. Er nutzt die zurückgegebenen service-IDs, um Bestellungen aufzugeben, und die Rate, um die Kosten vor dem Ausgeben zu bestätigen.

Anfrage

key=YOUR_API_KEY
action=services

Antwort

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. Bestellung hinzufügen

Der Schreibaufruf. Gibt eine Bestellung für einen Dienst auf. Übergib die service-ID, den Ziel-link und die quantity. Die Antwort liefert die neue order-ID zum Verfolgen zurück. Ein Agent führt dies erst aus, nachdem er Rate und Limits bestätigt hat.

Parameter

• service: Dienst-ID aus der Dienstliste
• link: die URL des Beitrags / Profils / Kanals
• quantity: Anzahl der zu liefernden Einheiten

Anfrage

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

Antwort

{
  "order": 23501
}

3. Bestellung hinzufügen, Drip-Feed

Teilt eine Bestellung in kleinere, über die Zeit verteilte Lieferungen auf, für eine gleichmäßigere Kurve. Lege runs (wie viele Lieferungen) und interval (Minuten dazwischen) fest. Die Gesamtliefermenge ist quantity × runs. Die Rechnung, die ein Agent nutzt, um eine Kampagne zu dimensionieren, ohne dass du es von Hand tust.

Zusätzliche Parameter

• runs: Anzahl der Lieferdurchläufe
• interval: Minuten zwischen den Durchläufen

Anfrage

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

Antwort

{
  "order": 23502
}

4. Bestellstatus

Gibt den aktuellen Zustand einer Bestellung zurück: Berechnung, Startzähler, Status, Restmenge und Währung. So beobachtet ein Agent eine Bestellung, ohne dass du das Dashboard aktualisierst, und so erkennt er einen Rückgang, der eine Nachfüllung wert ist.

Anfrage

key=YOUR_API_KEY
action=status
order=23501

Antwort

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

Mögliche status-Werte: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Status mehrerer Bestellungen

Prüfe viele Bestellungen in einem Aufruf. Übergib eine kommagetrennte Liste von IDs im Parameter orders. Die Antwort ist nach Bestell-ID indiziert, sodass ein Agent eine ganze Kampagne in einem einzigen Roundtrip abfragt, statt einen Aufruf pro Bestellung.

Anfrage

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

Antwort

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. Nachfüllen

Fordert eine Nachfüllung für eine Bestellung an, deren Dienst dies unterstützt (refill: true in der Dienstliste), und gibt eine Refill-ID zum Verfolgen zurück. Übergib eine einzelne order oder eine kommagetrennte orders-Liste. So kann ein Agent Nachfüllungen in großem Umfang anfordern, nachdem eine Statusprüfung Rückgänge gemeldet hat.

Anfrage (einzeln)

key=YOUR_API_KEY
action=refill
order=23501

Antwort

{
  "refill": 4001
}

Anfrage (mehrere)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Antwort

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. Stornieren

Fordert die Stornierung noch nicht verarbeiteter Bestellungen an (Dienste mit cancel: true). Übergib eine kommagetrennte orders-Liste; die Antwort meldet das Ergebnis pro Bestellung. Der Rückgängig-Knopf, zu dem ein Agent greift, wenn versehentlich etwas in die Warteschlange geraten ist.

Anfrage

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Antwort

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. Guthaben

Gibt dein Kontoguthaben und die Währung zurück. Ein Agent liest es, um Ausgaben vor einer Bestellung zu begrenzen, und dein eigenes Panel liest es, um das Guthaben anzuzeigen. Der günstigste Aufruf, um zu bestätigen, dass Geld zum Ausgeben da ist.

Anfrage

key=YOUR_API_KEY
action=balance

Antwort

{
  "balance": "182.45",
  "currency": "USD"
}

Rufe es von überall auf

Ein Endpunkt, einfache Formularparameter. So kann eine Shell, ein Cronjob oder ein Agent es auf dieselbe Weise steuern. Hier eine vollständige Bestellung, aufgegeben von der Kommandozeile:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

Hinweise & Best Practices

• Lesen, bevor du schreibst. Rufe services (oder balance) auf, um Rate, Limits und Guthaben zu bestätigen, und rufe dann add auf. Dieselbe Suchen-dann-Handeln-Leitplanke, die Dashboard und MCP-Server verwenden, damit nichts ohne bestätigten Preis ausgegeben wird.
• Cache die Dienstliste und aktualisiere sie regelmäßig – IDs, Raten und Limits ändern sich.
• Prüfe die min-/max-Mengen, bevor du eine Bestellung absendest, um abgelehnte Aufrufe zu vermeiden.
• Frage den Status in Stapeln mit dem Aufruf für mehrere Bestellungen ab, statt eine Anfrage pro Bestellung.
• Halte deinen Schlüssel serverseitig. Sollte er je offengelegt werden, rotiere ihn sofort über das Dashboard.