OpenSMM Protocol

Open, provider-neutral protocol for ordering and executing social media growth services by AI agents. MCP is one way to connect — not the product itself.

Status: 0.1.0-draft — the spec and reference gateway are feature-complete for the v0 draft and covered by tests; not yet published to npm or MCP registries.

For AI agents: start with llms.txt. For supply nodes: docs/PROVIDER_ONBOARDING.md — zero-code registration, including a copy-paste prompt for your AI assistant.

What this is

OpenSMM separates three concerns that classic SMM panels merge into one:

AI Agent
   │
   ▼
OpenSMM Gateway            ← catalog, quotes, payments, idempotency, MCP/REST
   │ canonical commands
   ▼
OpenSMM Provider SPI       ← execution suppliers behind one adapter interface
   │
   ▼
Execution providers        ← SMM API v2 panels, native providers, ...

• spec/v0/ — the protocol: JSON Schemas for every model, canonical statuses, error codes, idempotency rules, flow examples. Language- and transport-neutral.

• src/core/ — the domain core: catalog, quoting, orders, payment intents, execution state machine. No MCP/HTTP imports allowed in here.

• src/adapters/inbound/rest/ — canonical HTTP binding (/v0/*).

• src/adapters/inbound/mcp/ — MCP tools, a thin layer over the same core.

• src/adapters/providers/mock/ — in-memory provider for the vertical slice, with scriptable failure scenarios (rejection, ambiguous submission, cancel, refill).

• src/adapters/providers/smm-v2/ — one adapter for the de-facto SMM API v2 standard (POST /api/v2, key+action) with semantic profiles for panel deviations (per-unit rates, success-message refills, provider-credit currencies). Onboarding a panel = baseUrl + apiKey + profile.

• src/adapters/providers/rest-v1/ — adapter for reseller-style REST v1 APIs (GET /services, POST /orders, Bearer auth).

• src/core/provider-registry.ts + src/core/ssrf-guard.ts — multi-provider node registry (pseudonymous keys, lifecycle) and the SSRF guard behind registerProvider.

• src/adapters/payments/x402/ — x402 payment rail (USDC on Base) behind a facilitator interface; ships with a mock facilitator for tests. The core only knows the PaymentRail SPI, so TON/CryptoBot plug in the same way.

Related MCP server: tokportal-mcp

The one rule of the protocol

The same operation through REST and MCP produces the same domain objects. Same clientReference → same orderId, on any transport.

Quick start (local, MockProvider)

Requires Node.js ≥ 22.6 (runs TypeScript natively).

npm install
npm test          # 86 tests: core, transports, adapters, payments, registry, spec examples

REST:

npm run rest      # http://localhost:3100/v0
curl http://localhost:3100/v0/capabilities
curl "http://localhost:3100/v0/services?query=members&platform=telegram"

Connecting a live provider (rest-v1)

Both entry points boot against the MockProvider by default. To run the gateway against a live provider exposing a reseller-style REST v1 API (GET /services, POST /orders, GET /orders/:id, Bearer auth), set:

# .env (gitignored) or the environment of the process
OPENSMM_REST_V1_BASE_URL=https://provider.example/api/v1
OPENSMM_REST_V1_API_KEY=<reseller api key>
OPENSMM_PROVIDER_ID=provider-alpha   # optional, defaults to "rest-v1"

On boot the gateway syncs the catalog from the provider's GET /services and serves it through the same protocol surface. Order creation spends the provider-side balance of that API key — use a funded key only when you intend to place real orders.

MCP (stdio, for Claude Desktop / Kimi Code / Cursor):

{
  "mcpServers": {
    "opensmm": {
      "command": "npx",
      "args": ["-y", "@opensmm/mcp-server"]
    }
  }
}

or from a checkout: "command": "node", "args": ["/path/to/mcp-server/bin/opensmm.mjs"].

Tools: get_capabilities, list_providers, register_provider, search_services, get_service, get_quote, create_order, get_order_status, cancel_order, request_refill.

list_providers (REST: GET /v0/providers) returns the pseudonymous provider showcase: lifecycle, capabilities, offers count, and gateway-measured quality metrics. Providers are listed under opaque keys (provider-alpha, …); a human-readable displayName appears only for providers that opted in.

register_provider (REST: POST /v0/providers) is provider self-onboarding (spec/v0 §10): the endpoint URL must pass the SSRF guard, the gateway healthchecks the provider API by listing its offers, syncs them into the catalog and returns the pseudonymous providerKey. Credentials are used only to call the provider and are never returned. A payoutAddress enables direct settlement (spec/v0 §8): it becomes the payTo of that provider's payment requirements — money flows agent → provider, never through the gateway.

The acceptance flow

search → quote → create order → payment → execution → status → completion

# 1. quote (mandatory before ordering)
curl -X POST http://localhost:3100/v0/quotes -H 'content-type: application/json' \
  -d '{"serviceId":"osmm_svc_tg_members_std","quantity":1000,"link":"https://t.me/example_channel"}'

# 2. order — returns HTTP 402 with the Order body (paymentStatus: REQUIRES_PAYMENT)
curl -X POST http://localhost:3100/v0/orders \
  -H 'content-type: application/json' -H 'Idempotency-Key: my-order-1' \
  -d '{"quoteId":"<quoteId>","link":"https://t.me/example_channel"}'

# 3. settle via the dev-only mock rail
curl -X POST http://localhost:3100/v0/payments/<paymentIntentId>/settle

# 4. poll
curl http://localhost:3100/v0/orders/<orderId>

Key properties (enforced by tests):

• Idempotency is part of the protocol. Idempotency-Key header (REST) / clientReference (MCP). Replay returns the same order; same key with different parameters → IDEMPOTENCY_CONFLICT.

• Payment and execution are separate state machines (paymentStatus vs executionStatus), never one merged status.

• No blind provider retries. An ambiguous submission becomes SUBMISSION_UNKNOWN and waits for reconciliation — it is never silently resent.

• Money is decimal strings, computed on integer micro-units. No floats.

• A quote is consumed exactly once; reuse returns the original order instead of double-charging.

Roadmap

1. ✅ Spec draft: JSON Schemas, errors, statuses, examples.

2. ✅ Core: quote, order, idempotency, state machine.

3. ✅ MockProvider: full lifecycle + failure scenarios.

4. ✅ REST + MCP: same scenario through both transports, same orderId.

5. ✅ Provider adapters: smm-v2 (classic panel API with behavior profiles) and rest-v1 (reseller-style REST).

6. ✅ Multi-provider registry + registerProvider self-onboarding with SSRF guard, healthcheck and live catalog sync.

7. ✅ Direct settlement: provider payoutAddress becomes the payTo of its payment requirements — funds flow agent → provider, never through the gateway.

8. 🟡 x402: rail with mock facilitator done (incl. SETTLEMENT_PENDING); testnet needs a real facilitator config.

9. ⬜ Background catalog sync + healthchecks with circuit breaker (SUSPENDED on degradation).

10. ⬜ Gateway-measured metrics feeding the public provider showcase.

11. ⬜ x402 mainnet: real small-amount payment.

12. ⬜ Public MVP: 30–50 curated services. No account farms, no A2A yet.

Legal notice

OpenSMM is open-source software for routing and measuring API requests. It is not a marketplace operator, payment processor or escrow agent: with direct settlement, funds move peer-to-peer between agents and providers, and the software never holds balances or private keys. Quality metrics are gateway-measured observations, not guarantees. Each gateway operator and each provider node is responsible for its own compliance. The software is provided "as is", without warranty of any kind — see LICENSE.

License

MIT © OpenSMM Protocol — see LICENSE.