Protocols and APIs

Engines communicate with the PolySwarm Marketplace using:

Inbound webhooks from PolySwarm to your Engine
Outbound callbacks from your Engine to PolySwarm (artifact download and analysis submission)

You do not need to implement blockchain interactions.

Inbound webhook, PolySwarm to Engine

PolySwarm sends HTTP POST requests to the webhook URL configured for your Engine.

HTTPS requirement

Your webhook endpoint must be publicly reachable over HTTPS using an FQDN.

Use HTTPS only
Use a fully qualified domain name (FQDN)
You may include a path in the URL

Standard headers

PolySwarm includes headers on webhook calls. Common headers include:

X-POLYSWARM-DELIVERY (unique delivery id)
X-POLYSWARM-EVENT (event type, for example bounty or ping)
X-POLYSWARM-SIGNATURE (HMAC signature for sender validation)

Header names can vary by implementation, so treat the above as a reference and follow the Engine template you are using.

Signature validation

Your server should validate that PolySwarm sent the request by verifying the signature header against the raw request body using the shared secret configured for the webhook.

If signature validation fails, reject the request (commonly 401 or 403) and do not process the bounty.

Event, ping

Ping is a connectivity test.

Method: POST
Event header: X-POLYSWARM-EVENT: ping

Recommended response:

Status: 202
Body:
```
{ "status": "OK" }
```

Event, bounty

Bounty is the main event. It tells your Engine what to analyze.

Method: POST
Event header: X-POLYSWARM-EVENT: bounty
Body: JSON bounty payload

Typical bounty payload

Field names vary slightly by tooling, but the concepts are consistent.

{
  "id": 1234567890,
  "artifact_type": "file",
  "artifact_uri": "https://api.polyswarm.network/path/to/download",
  "expiration": "1970-01-01T00:00:00+0000",
  "response_url": "https://api.polyswarm.network/path/to/respond",
  "phase": "assertion",
  "sha256": "optional-for-file",
  "mimetype": "optional-for-file",
  "rules": {
    "min_allowed_bid": 625000000000,
    "max_allowed_bid": 1000000000000000000
  }
}

Note: The above min_allowed_bid and max_allowed_bid values are in units of NCT-WEI.

Expected webhook server behaviour

Your webhook server should:

validate signature
enqueue work for a worker
return quickly

Recommended success response:

Status: 202
Body:
```
{ "status": "ACCEPTED" }
```

If the payload is invalid (missing required fields), return a client error (commonly 400).

Outbound callbacks, Engine to PolySwarm

1) Artifact download (file artifacts)

To fetch a file artifact, your Engine downloads from artifact_uri (or equivalent field).

Method: GET
URL: artifact_uri

Expected success:

Status: 200
Response body: binary file content

2) Submit analysis (assertion)

Your Engine posts the analysis result to response_url (or equivalent field).

Method: POST
URL: response_url
Content-Type: application/json

Payload:

{
  "verdict": "malicious",
  "bid": 1000000000000000000,
  "metadata": {
    "malware_family": "EICAR-TEST-FILE",
    "confidence": 1.0,
    "scanner": {
      "version": "1.0.0",
      "environment": {
        "operating_system": "Linux",
        "architecture": "x86_64"
      }
    }
  }
}

Rules:

bid must be an integer in NCT-wei
bids must respect min_allowed_bid and max_allowed_bid
unknown and unsupported cases should return bid 0
metadata is optional but recommended, keep it stable and meaningful

Required behaviour summary

validate signature on inbound webhooks
return 202 quickly and scan asynchronously
fetch artifacts from the provided URI and enforce timeouts
post a correctly formatted analysis to the provided response URL before expiration
return UNKNOWN for unsupported types, failures, and timeouts