Provider Docs

Daemon HTTP API

The provider daemon serves a small HTTP surface under /v1/*. Clients use it to deliver deal bytes and fetch content; you use it to check on your node. This is the API your registered endpoint exposes — for the hosted gateway's API, see the API Reference.

iNote

There is no HTTP authentication. Writes are gated on-chain: an upload is only accepted when its recomputed Merkle root matches the commitment of an Accepted deal directed at this provider, so a stranger cannot store bytes or trigger transactions they did not already pay for. Errors are always { "error": "…" } JSON.

Routes

GET/v1/infoDaemon identity and capacity PUT/v1/deals/:dealId/dataUpload a deal's file bytes GET/v1/content/:merkleRootRetrieve stored content GET/v1/deals/:dealIdDeal status (local + on-chain)

Daemon info

GET/v1/info

Identity and capacity of the node: the provider address, connected chain and market contract, advertised versus used bytes, whether auto-accept is on, and the daemon version. Use it to verify public reachability after deploy.

Request

curl https://<your-provider-domain>/v1/info

200 · application/json

{
  "provider": "0x1234…abcd",
  "chainId": 46630,
  "market": "0x5678…ef01",
  "capacityBytes": 10737418240,
  "usedBytes": 52428800,
  "autoAccept": true,
  "version": "0.1.0"
}

Upload deal data

PUT/v1/deals/:dealId/data

Delivers the file bytes for an Accepted deal. The body is the raw file as application/octet-stream. The daemon re-chunks the bytes, recomputes the Merkle root, and only if root, size, and leaf count all match the on-chain commitment does it persist the chunks and call activateDeal. Re-uploading to an already Active deal re-verifies and re-persists without a new transaction.

Request

curl -X PUT https://<your-provider-domain>/v1/deals/42/data \
  -H "content-type: application/octet-stream" \
  --data-binary @report.pdf

200 · application/json

{
  "dealId": 42,
  "merkleRoot": "0xabc…123",
  "activated": true
}

Status	When
400	dealId is not a decimal integer; empty body; Merkle root mismatch; size or leaf-count mismatch.
403	The deal is not directed at this provider.
404	Deal not found on-chain.
409	Deal status is not Accepted or Active (e.g. still Created, or already Completed).

Retrieve content

GET/v1/content/:merkleRoot

Streams the stored bytes for a Merkle root as application/octet-stream with content-length set. The root parameter accepts hex with or without the 0x prefix. Clients verify what they receive against the on-chain root, so the transport needs no trust.

Request

curl -o report.pdf \
  https://<your-provider-domain>/v1/content/0xabc…123

Status	When
400	Parameter is not a valid 32-byte hex Merkle root.
404	No content stored for that root.

Deal status

GET/v1/deals/:dealId

Both views of one deal: local is the daemon's manifest record (null if it holds none), onchain is the full StorageMarket deal struct (null if the chain does not know the id). Top-level status prefers the on-chain name.

Request

curl https://<your-provider-domain>/v1/deals/42

200 · application/json

{
  "dealId": 42,
  "status": "Active",
  "local": {
    "root": "0xabc…123",
    "sizeBytes": 52428800,
    "leafCount": 51200,
    "status": "Active",
    "activatedAt": 1754500000
  },
  "onchain": {
    "client": "0x9abc…def0",
    "provider": "0x1234…abcd",
    "merkleRoot": "0xabc…123",
    "leafCount": 51200,
    "sizeBytes": 52428800,
    "duration": 2592000,
    "createdAt": 1754490000,
    "acceptedAt": 1754495000,
    "startTime": 1754500000,
    "endTime": 1757092000,
    "lastChallengeAt": 0,
    "totalPrice": "5000000000000000000",
    "collateral": "2500000000000000000",
    "slashPerFault": "833333333333333333",
    "paidOut": "0",
    "faultCount": 0,
    "status": 2,
    "statusName": "Active"
  }
}

Status	When
400	dealId is not a decimal integer.
404	Deal unknown both locally and on-chain.