OpenSMM Protocol
Giao thức mở, trung lập với nhà cung cấp và cổng MCP tham chiếu để các tác nhân AI đặt mua dịch vụ tăng trưởng mạng xã hội (người theo dõi, lượt xem, lượt tương tác): tìm kiếm danh mục, báo giá, đơn hàng có tính lũy đẳng và đăng ký nút nhà cung cấp. Chạy cục bộ từ bản sao mã nguồn; hỗ trợ stdio và Streamable HTTP.
Tài liệu
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.1 — first public release. The spec and reference gateway are
feature-complete for v0 and covered by tests.
Run a node: docs/NODES.md (node checks, public URL) ·
docs/DEPLOY.md (Docker, TLS, state).
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 behindregisterProvider.src/adapters/payments/x402/— x402 payment rail (USDC on Base) behind a facilitator interface; ships with a mock facilitator for tests, and an HTTP facilitator client (X402_FACILITATOR_URL, seedocs/X402_TESTNET.md) for live testnet/mainnet settlement. The core only knows thePaymentRailSPI, so TON/CryptoBot plug in the same way.
Run a node from source in 5 minutes
There is one install source — a checkout of this repository. With Node.js ≥ 22.18 that is all you need; the Docker one-liner right below builds the same node from the same checkout.
git clone https://github.com/opensmm-protocol/mcp-server.git
cd mcp-server
npm ci
npm run gateway
The node reports its port on stderr:
OpenSMM 0.1.1 gateway listening on http://localhost:8080 (REST /v0, MCP /mcp; provider: mock, mock catalog — not real supply)
Check the node:
curl -s http://localhost:8080/v0/services | head -30 # every service has "synthetic": true
curl -s http://localhost:8080/v0/providers # provider-alpha, synthetic: true
curl -s -X POST http://localhost:8080/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"qa","version":"1"}}}' # serverInfo.name = "opensmm"
npm run census -- --url http://127.0.0.1:8080 # "status": "up"
node scripts/node-census.mjs --url http://127.0.0.1:8080 # same check without npm
npm run verify:node -- http://127.0.0.1:8080 # PASS/FAIL per census check; exit 0 = the census counts this node
The catalog you see is the mock catalog: it is not sellable supply and no
real order is executed — it exists to exercise the protocol end to end. The
live catalog appears only after you connect a provider (see
«Connecting a live provider (rest-v1)» below). Independent node checks with
the census tool: docs/NODES.md.
How an agent orders from that node, over REST and over MCP, with the
idempotent replay: examples/.
Troubleshooting common startup issues (port conflict, Node version, state file permissions, offline npm ci, mock catalog):
docs/TROUBLESHOOTING.md.
Running a public node? Report its URL for the weekly census via the issue template:
issues/new?template=node-report.md.
Need a public URL without setting up a domain or Caddy first? See
docs/NODES.md («Public URL without a custom domain»).
The one rule of the protocol
The same operation through REST and MCP produces the same domain objects. Same
clientReference→ sameorderId, on any transport.
Install routes: from source, and Docker from the same source
There is no npm package and no public container image for this gateway, and
none is planned — a node is installed from this repository. Two equivalent
routes start the same node (same REST /v0, same MCP /mcp, same mock
catalog):
- From source — the
git clone … && npm run gatewayblock above. - Docker — one command, from zero (nothing checked out yet); Docker builds the image from the same sources:
git clone https://github.com/opensmm-protocol/mcp-server.git && cd mcp-server && docker build -t opensmm-gateway . && docker run -d --name opensmm -p 127.0.0.1:8080:8080 -v opensmm-data:/data opensmm-gateway
The node answers within a few seconds — the check that it is up:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/v0/services # 200
Docker details — docker compose, state on the volume, healthcheck, systemd,
TLS: docs/DEPLOY.md.
Local development
The checkout also starts single transports, for tests and debugging. To start the node itself, use «Run a node from source in 5 minutes» above.
npm install
npm test # tests: core, transports, adapters, payments, registry, spec examples
npm run rest # http://localhost:3100/v0 — REST only
npm run mcp # stdio — point your MCP client at this process
npm run mcp:http # http://localhost:3200/mcp — stateless Streamable HTTP, open CORS
Production deployment (Docker, TLS, state persistence): docs/DEPLOY.md.
Checking a panel before you connect it (smm-v2)
Read-only Level-0 check of a classic SMM API v2 panel — HTTPS and JSON vs
HTML/Cloudflare, action=balance, action=services, envelope and field
aliases — plus a suggested profile and a ready connection snippet. Nothing is
registered and the key is never printed:
# the key is read from OPENSMM_PANEL_KEY: it stays out of argv and the npm command echo
OPENSMM_PANEL_KEY=<key> npm run doctor -- --url https://panel.example/api/v2
OPENSMM_PANEL_KEY=<key> node bin/opensmm.mjs doctor --url https://panel.example/api/v2
An inline assignment is still visible in ps and the shell history. To keep it
out of both, put the key in .env.panel (gitignored by the .env.* rule) and
load it with set -a; . ./.env.panel; set +a, or type it without echo:
read -rs OPENSMM_PANEL_KEY; export OPENSMM_PANEL_KEY.
Exit 0 — all checks passed; 1 — a check failed. Details:
docs/PROVIDER_ONBOARDING.md.
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) — point the client at a checkout:
{
"mcpServers": {
"opensmm": {
"command": "node",
"args": ["/path/to/mcp-server/bin/opensmm.mjs"]
}
}
}
(run npm run build once in the checkout — the entry point runs dist/,
because Node refuses TypeScript type stripping inside node_modules).
There is no npm package to install instead: the config always points at a
checkout, which is the only install route.
Tools: get_capabilities, list_providers, register_provider,
search_services, compare_offers, 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.
Choosing between providers for the same service: search_services enriches
every offer with providerRef (the pseudonymous provider key) and quality
(gateway-measured orders, deliveredRatio, startLatencyMs), and accepts
sort=price|quality|relevance (relevance is the default and keeps the
catalog order). compare_offers (MCP tool) goes one step further: one
cheapest offer per provider for a platform+objective, cheapest first,
with measured quality and the total price for your quantity — SUSPENDED
providers are excluded. Prices are ranked inside a single currency and never
converted: compare_offers reports the currency it ranked in (pass
currency to choose it — codes are matched case-insensitively; the default is
the most offered currency that can deliver your quantity) and lists any other
currencies in excludedCurrencies. GET /v0/services supports the same
sort parameter.
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.
Public MVP: curated catalog
The gateway can serve a curated catalog — a hand-reviewed snapshot of sellable services — instead of calling a provider on boot. Every record keeps its provenance, so each published price can be traced back to the provider offer it was copied from.
OPENSMM_CURATED_CATALOG=./data/curated-services.json npm run rest
Without OPENSMM_CURATED_CATALOG the gateway behaves exactly as before: mock
seed in local dev, live sync against a configured provider.
Catalog file format
data/curated-services.json holds the wire Service (spec/v0 §4) plus a
provenance block and curation metadata:
{
"format": 1,
"version": "2026-11-06T00:00:00Z",
"entries": [
{
"example": true,
"rating": 4.6,
"provenance": {
"providerId": "mock",
"externalServiceId": "1001",
"sourceUrl": "https://example.invalid/mock/services/1001",
"syncedAt": "2026-11-06T00:00:00Z"
},
"service": { "serviceId": "osmm_svc_…", "name": "…" }
}
]
}
service— one record of the wireServicemodel: platform, objective, rate, rate basis, min/max quantity, capabilities.provenance.providerId/externalServiceId— the provider offer this service maps to; orders route to that provider node.provenance.sourceUrl— the provider-side page or API URL the offer came from (https://only).provenance.syncedAt— when the offer was copied (ISO-8601 UTC).rating— optional curator score, 0–5. The wireServicehas no rating field: spec/v0 publishes gateway-measured metrics only, so this is curation metadata, not a protocol claim.example—truemarks a placeholder record that must never reach a production catalog.
Validation is fail-closed: one bad record stops the gateway at boot with the offending path and reason. Enforced rules:
- unique
serviceId; uniqueproviderId + externalServiceIdpair; provenanceis mandatory,sourceUrlmust behttps://,syncedAtmust be an ISO-8601 timestamp;- rate value between
0.000001and10000per rate basis,maxQuantity >= minQuantity; - every
provenance.providerIdmust match a provider registered at boot, otherwise the catalog would advertise services the gateway cannot route.
The checked-in data/curated-services.json contains three example records
(telegram members, telegram views, youtube views) copied from the mock seed.
It exists to exercise the schema and tests — it is not a production catalog.
As soon as a live provider is configured (OPENSMM_REST_V1_BASE_URL), a
catalog with example records is rejected at boot: a public gateway must not
serve placeholders a buyer cannot tell apart from a sellable service.
How to add a service
- Take a live offer from the provider's own catalog. Do not invent names, prices, limits or capabilities — if the provider catalog is unreachable, stop and escalate instead of filling the gap.
- Copy the offer into a
servicerecord.serviceIdis gateway-stable: keep it when the price changes, never reuse it for a different offer. - Fill
provenance(providerId,externalServiceId,sourceUrl,syncedAt).providerIdmust be registered on the gateway at boot. - Drop
example(or setfalse) once the record is real, then runnpm testand start the gateway withOPENSMM_CURATED_CATALOG.
Curated snapshot vs provider live sync
| Curated catalog | Provider live sync | |
|---|---|---|
| Source | reviewed JSON file in the repo | provider API at boot + every 5 min |
| Boot | no provider call needed | listOffers healthcheck |
| Content | hand-picked subset | everything the provider returns |
| Price drift | frozen until the file is re-synced | follows the provider |
| Background sync | disabled (would overwrite the review) | enabled, with circuit breaker |
Both modes serve the same REST /v0/services and MCP search_services
surface. Order polling, retention checks and payment rails are unaffected by
the mode.
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-Keyheader (REST) /clientReference(MCP). Replay returns the same order; same key with different parameters →IDEMPOTENCY_CONFLICT. - Payment and execution are separate state machines (
paymentStatusvsexecutionStatus), never one merged status. - No blind provider retries. An ambiguous submission becomes
SUBMISSION_UNKNOWNand 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.
How agents find us
Three entry points, any of them leads to the same server:
- Source checkout —
git clone … && npm ci && npm run gateway(or the Docker one-liner above). No npm package exists: the checkout is the install. llms.txt—llms.txtis the compact machine-readable summary of the protocol, the tools and the docs.- Website — https://opensmm.dev for the human-facing view of the same material.
There is no MCP Registry entry and none can appear until there is a published
package or a public hosted endpoint; the node is installed from source — see
Run a node from source in 5 minutes.
Details: docs/REGISTRY.md.
Roadmap
- ✅ Spec draft: JSON Schemas, errors, statuses, examples.
- ✅ Core: quote, order, idempotency, state machine.
- ✅ MockProvider: full lifecycle + failure scenarios.
- ✅ REST + MCP: same scenario through both transports, same
orderId. - ✅ Provider adapters:
smm-v2(classic panel API with behavior profiles) andrest-v1(reseller-style REST). - ✅ Multi-provider registry +
registerProviderself-onboarding with SSRF guard, healthcheck and live catalog sync. - ✅ Direct settlement: provider
payoutAddressbecomes thepayToof its payment requirements — funds flow agent → provider, never through the gateway. - 🟡 x402: rail done (incl.
SETTLEMENT_PENDING) with a real facilitator client configured via env — testnet setup and live-run script indocs/X402_TESTNET.md. First live Base Sepolia payment pending a funded payer key (in progress). - ✅ Background catalog sync + healthchecks with circuit breaker
(
SUSPENDEDon degradation). - ✅ Gateway-measured metrics feeding the public provider showcase.
- ⬜ x402 mainnet: real small-amount payment.
- ⬜ Public MVP: 30–50 curated services. No account farms, no A2A yet.
- ⬜ Supply integration: onboard the ProstoSpets panel (SMM API v2) as a live
provider node via the
smm-v2adapter. Waits for the panel API key.
Source of truth for status: PROJECT.md.
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.