# Ocean Node Api
## Release note — `decryptDDO` signed-message change (ON-02, BREAKING)
As of Ocean Node **v4.8.0**, the `decryptDDO` signature scheme is bound to the destination node's
peerId and to the specific resource (`chainId + transactionId + dataNftAddress`), and the signing
node uses a local monotonic nonce instead of trusting a nonce fetched from the on-chain
`decryptorURL`. See the HTTP `POST /api/services/decrypt` and P2P `decryptDDO` sections for the
exact message.
This is a coordinated signer/verifier change and is **not backwards compatible** between node
versions. When nodes on different versions talk to each other over **HTTP**, the signed message
will not match, the HTTP decrypt attempt fails, and the Indexer **falls back to the existing P2P
decrypt path** — which is safe (no silent downgrade). Mixed-version HTTP decrypt therefore keeps
working via P2P until **both** sides are upgraded. There is intentionally no "accept the old
message too" path, because that would re-open the cross-node signature-replay vulnerability this
change closes. Client libraries that construct the `decryptDDO` message themselves
(`ocean.js` / indexer clients) must adopt the new format.
---
## Address casing
Every EVM address you send (`consumerAddress`, `owner`, `address`, `decrypterAddress`,
`dataNftAddress`, `publisherAddress`, `consumerAddrs`, `additionalViewers`) is accepted in **any
casing** — checksummed (EIP-55), all-lowercase, all-uppercase — and canonicalized to its checksummed
form by the node before it is used as a lookup key or compared against an owner. A lowercased
address therefore matches the same jobs, services and buckets as the checksummed one.
Signatures are unaffected: the node verifies the signed message against the casing you actually
signed, so clients that build the message from a lowercase address keep working.
---
## State DDO
### `HTTP` GET /api/aquarius/assets/metadata/query?
#### Description
returns ddo state
#### Query Parameters
| name | type | required | description |
| ------- | ------ | -------- | ------------------------------------------------------ |
| did | object | | document id or did |
| chainId | object | | chain id of network on which document is provided |
| nft | object | | one or more field names that should be queried against |
#### Response
```
123
```
---
## Query DDO
### `HTTP` POST /api/aquarius/assets/metadata/query
#### Description
returns search result for query
#### Parameters
| name | type | required | description |
| -------- | ------ | -------- | ------------------------------------------------------ |
| q | object | v | text to search for in database |
| query_by | object | v | one or more field names that should be queried against |
#### Request
```json
{
"q": "0x123",
"query_by": "nftAddress"
}
```
#### Response
```
[{
"facet_counts": [],
"found": 1,
"out_of": 1,
"page": 1,
"request_params": {
"collection_name": "ddo",
"per_page": 10,
"q": "0x123"
},
"search_time_ms": 1,
"hits": [
{
"highlights": [
{
"field": "nftAddress",
"snippet": "0x123",
"matched_tokens": ["0x123"]
}
],
"document": {
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
},
"text_match": 130916
}
]
}]
```
---
## Get DDO Metadata
### `HTTP` GET /api/aquarius/assets/ddo/:did
#### Description
returns metadata of document by id
#### Response
```
{
"created": "2020-11-15T12:27:48Z",
"updated": "2021-05-17T21:58:02Z",
"description": "Sample description",
"name": "Sample asset",
"type": "dataset",
"author": "OPF",
"license": "https://market.oceanprotocol.com/terms"
}
```
---
## Get DDO
### `HTTP` GET /api/aquarius/assets/ddo/:did
#### Description
returns document by id
#### Response
```
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
}
```
---
## Nonce
### `HTTP` GET /api/services/nonce?
#### Description
returns stored nonce for an address
#### Query Parameters
| name | type | required | description |
| ----------- | ------ | -------- | ----------- |
| userAddress | string | v | address |
#### Response
```
123
```
---
## Initialize Service
### `HTTP` GET /api/services/initialize?
#### Description
returns amount of tokens to transfer to the provider account
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | ---------------------------------------------- |
| documentId | string | v | document id or did |
| serviceId | string | v | id of the service the datatoken is attached to |
| consumerAddress | string | v | consumer address |
#### Response
```
{
"datatoken": "0x123",
"nonce": "123",
"providerFee": {
providerFeeAddress: "0x123",
providerFeeToken: "0x123",
providerFeeAmount: 123,
providerData: "0x123",
v: 123,
r: "0x123",
s: "0x123",
validUntil: 123
}
}
```
---
## Encrypt
### `HTTP` POST /api/services/encrypt
#### Description
returns encrypted blob
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | ------------------------------------------------------- |
| nonce | string | v | is required to verify a request paired with a signature |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message based on ` nonce` |
#### Request body
```
string
```
#### Response
```
0x123
```
---
## EncryptFile
### `HTTP` POST /api/services/encryptFile
#### Description
returns encrypted file
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | ------------------------------------------------------- |
| nonce | string | v | is required to verify a request paired with a signature |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message based on ` nonce` |
#### Request body
if Content-Type = 'application/json'
```
BaseFileObject
```
if Content-Type = 'application/octet-stream' || 'multipart/form-data'
```
FileContent(bytes)
```
#### Response
```
0x123
```
---
## Decrypt DDO
### `HTTP` POST /api/services/decrypt
#### Description
returns decrypted document
#### Parameters
| name | type | required | description |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| decrypterAddress | string | v | decrypter address |
| chainId | number | v | chain id of network on which document is provided |
| transactionId | string | | tx id of encrypted document |
| dataNftAddress | string | | address of nft token |
| encryptedDocument | string | | encrypted document |
| flags | number | | metadata flags if DDO is ECIES encrypted or lzma compressed |
| documentHash | string | | hash based on sha256 of asset |
| nonce | string | v | is required to verify a request paired with a signature |
| signature | string | v | signed message (see below) |
> **ON-02 signed-message format (BREAKING, since Ocean Node v4.8.0).** The `decryptDDO`
> signature now binds the **destination node** and the **exact resource**, so a signature cannot
> be replayed against another node or for another asset. The signed message is:
>
> ```
> decrypterAddress + nonce + "decryptDDO" + issuerPeerId + chainId + transactionId + dataNftAddress
> ```
>
> - `issuerPeerId` is the **target (decrypting) node's own peerId** — i.e. the `nodeId` returned
> by that node's root `GET /` endpoint. A signature minted for node A is rejected by node B.
> - `chainId`, `transactionId`, `dataNftAddress` bind the signature to a single decrypt.
> - `nonce` is a client-local monotonic value (the Indexer uses `Date.now()`); the node no longer
> fetches a nonce from the (untrusted) `decryptorURL`.
>
> This is a coordinated signer/verifier change. A node on the old scheme talking to a node on the
> new scheme will **fail the HTTP decrypt and fall back to the P2P decrypt path** (see the release
> note below); there is deliberately no "accept the old message" fallback.
#### Request
```json
{
"decrypterAddress": "0x123",
"chainId": 123,
"transactionId": "0x123",
"dataNftAddress": "0x123",
"encryptedDocument": "0x123",
"flags": 1,
"documentHash": "0x123",
"nonce": "123",
"signature": "0x123"
}
```
#### Response
```
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
}
```
---
## File Info
### `HTTP` POST /api/fileInfo
#### Description
returns file information
Files whose host is, or resolves to, a private, loopback, link-local or otherwise reserved address are rejected (for example `URL points to a private, loopback or reserved network address`). Node operators can allow specific ranges with `ALLOWED_PRIVATE_URL_RANGES`; see [Storage](Storage.md#private-network-protection-ssrf).
#### Parameters
| name | type | required | description |
| --------- | ------ | -------- | --------------------------------------------------- |
| type | string | | type of storage `url or arweave or ipfs` |
| did | string | | document id or did |
| serviceId | number | | service id of services list |
| fileIndex | number | | file index in files array |
| file | object | | file data |
| checksum | number | | index in transaction events list |
#### Raw-`file` path hardening (ON-07)
A raw `file` object (as opposed to `did` + `serviceId`) needs **no signature or auth token** — it
only returns metadata (`contentLength`, `contentType`, `checksum`) of a URL the caller already
supplied, so authentication would gate nothing. Two protections apply instead, both independent of
caller identity:
- **Forwarded-header allow-list.** Any custom headers supplied inside the `file` object are
filtered to an allow-list (`accept`, `accept-encoding`, `range`, `content-type`, extended by
`FILEINFO_ALLOWED_HEADERS`) before the node fetches the target; `authorization`, `cookie` and
other headers are dropped, so the caller cannot inject credentials into a request to an internal
service.
- **Dedicated rate limit.** The raw-`file` path can be throttled independently of the global limit
via `FILEINFO_MAX_REQ_PER_MINUTE` (separate bucket), bounding its use as an amplification
primitive. SSRF to private/loopback/metadata targets is blocked by the address guard
(`ALLOWED_PRIVATE_URL_RANGES` / `UNSAFE_URLS`).
The `did` + `serviceId` path is unchanged: it keeps its existing DDO-based access control.
#### Request
```json
{
"type": "123",
"did": "did:op:123",
"serviceId": 123,
"fileIndex": 123,
"file": 123,
"checksum": 123
}
```
#### Response
```
[
{
valid: true
contentLength: "123"
contentType: "123"
name: "123"
type: "url or arweave or ipfs"
}
]
```
---
## Download
### `HTTP` GET /api/services/download?
#### Description
returns a file stream of the requested file
#### Query Parameters
| name | type | required | description |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| fileIndex | number | v | file index in the list of document files |
| documentId | string | v | document id or did |
| serviceId | string | v | service id of array of services defining access to the asset |
| transferTxId | string | v | tx id of transaction for approval of datatokens transfer given to the provider's account |
| nonce | string | v | is required to verify a request paired with a signature |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message based on `did + nonce` |
| aes_encrypted_key | string | | encrypted key for cipher to decrypt file |
#### Response
```
byte array
```
---
## Log
### `HTTP` POST /log/:id
#### Description
returns log by id. Admin only. Works only with `LOG_DB` and an available log database; otherwise returns `404`.
#### Parameters
| name | type | required | description |
| --------- | ------ | -------- | ----------------------------------------------------- |
| logId | string | v | id of the log entry (read from the body) |
| address | string | v | admin address (must be in `ALLOWED_ADMINS`) |
| signature | string | (v) | signed message — required unless an auth token is sent (read-only admin; token goes in the `Authorization` header) |
| nonce | string | (v) | nonce used for the signature |
#### Response
```
{
"timestamp": "123",
"level": "123",
"message": "123",
"moduleName": "123",
"meta": "123",
}
```
---
## Logs
### `HTTP` POST /logs
### `P2P` command: getLogs (`PROTOCOL_COMMANDS.GET_LOGS`)
#### Description
returns list of logs, newest first. Admin only: send `address`, `signature` and `nonce`. `getLogs` is a **read-only admin command**, so it also accepts a scoped **auth token** (send it in `authorization`) scoped to `getLogs` — the `ALLOWED_ADMINS` gate still applies to the token's authenticated address. (Mutating admin commands still reject tokens.) The default window is the last 7 days.
Source: the log database when `LOG_DB` is on and the log database is available; otherwise the rotating files in `logs/` (see [Logs.md](Logs.md)). Entries read from files have no `id` and only include levels at or above `LOG_FILES_LEVEL`. When nothing matches, the response is `200` with `[]`. An invalid `startTime`/`endTime` returns `400`.
#### Parameters
| name | type | required | description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| address | string | v | admin address (must be in `ALLOWED_ADMINS`) |
| signature | string | (v) | signed message — required unless an `authorization` token is sent |
| authorization | string | | scoped auth token (alternative to signature; read-only admin command) |
| nonce | string | (v) | nonce used for the signature |
| startTime | string | | filter logs from date (ISO 8601 or epoch ms). Default: 7 days before end |
| endTime | string | | filter logs to date (ISO 8601 or epoch ms). Default: now |
| maxLogs | number | | logs per page. Default `100`, maximum `1000` |
| moduleName | string | | filter logs by module name (case-insensitive) |
| level | string | | filter logs by level |
| page | number | | 1-based page number |
`startTime`, `endTime`, `maxLogs`, `moduleName`, `level` and `page` are sent as query parameters over HTTP.
#### Response
```
[
{
"id": "123",
"timestamp": "123",
"level": "123",
"message": "123",
"moduleName": "123",
"meta": "123",
}
]
```
`id` is present only for entries from the log database.
---
## Get providers for a string
### `HTTP` GET /getProvidersForString/?input=did:op:123"
#### Description
returns list of nodes providing the specific element(s) (dids, c2d resources, etc)
#### Query Parameters
| name | type | required | description |
| ----- | ------ | -------- | ---------------------- |
| input | string | v | did, c2d resource, etc |
## Get providers for a list of strings
### `HTTP` POST /getProvidersForStrings?timeout=10"
#### Description
returns list of nodes providing all specific elements.
#### Query Parameters
| name | type | required | description |
| ------- | ------ | -------- | ---------------------- |
| timeout | string | optional | timeout in miliseconds |
#### Request
```json
["{\"c2d\":{\"free\":false,\"disk\":1}}", "{\"c2d\":{\"free\":false,\"cpu\":1}}"]
```
#### Response
```json
[
{
"id": "16Uiu2HAmENNgCY1QAdQrPxipgUCQjyookUgpnbgXua4ZMju4Rkou",
"multiaddrs": [
"/ip4/10.255.255.254/tcp/41015/ws",
"/ip4/10.255.255.254/tcp/41347",
"/ip4/127.0.0.1/tcp/41015/ws",
"/ip4/127.0.0.1/tcp/41347",
"/ip4/172.27.58.101/tcp/41015/ws",
"/ip4/172.27.58.101/tcp/41347",
"/ip6/::1/tcp/37527"
]
}
]
```
---
## Get P2P Peer
### `HTTP` GET /getP2PPeer/?
#### Description
returns P2P peer
#### Query Parameters
| name | type | required | description |
| ------ | ------ | -------- | ----------- |
| peerId | string | v | peer id |
#### Response
```
{
"id": "PeerId",
"addresses": [{ multiaddr: "123", isCertified: true }],
"protocols": ["123", "123", "123"],
"metadata": {},
"tags": {},
"publicKey": "0x123"
}
```
---
## find peer multiaddress
### `HTTP` GET /findPeer/?
#### Description
returns P2P peer multiaddresses if found in DHT
#### Query Parameters
| name | type | required | description |
| ------- | ------ | -------- | ----------- |
| peerId | string | v | peer id |
| timeout | int | optional | timeout |
#### Response
```
{
"id": "16Uiu2HAmLhRDqfufZiQnxvQs2XHhd6hwkLSPfjAQg1gH8wgRixiP",
"multiaddrs": [
"/ip4/127.0.0.1/tcp/9000",
"/ip4/127.0.0.1/tcp/9001/ws",
"/ip4/172.18.0.2/tcp/9000",
"/ip4/172.18.0.2/tcp/9001/ws",
"/ip6/::1/tcp/9002"
]
}
```
---
## Get P2P Peers
### `HTTP` GET /getP2PPeers
#### Description
returns list of all P2P peers
#### Response
```
[
{
"id": "PeerId",
"addresses": [{ multiaddr: "123", isCertified: true }],
"protocols": ["123", "123", "123"],
"metadata": {},
"tags": {}
}
]
```
---
## Validate DDO
### `HTTP` POST /directCommand
### `P2P` command: validateDDO
#### Description
returns an empty object if it is valid otherwise an array with error
#### Parameters
| name | type | required | description |
| ---------- | -------- | -------- | ------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| multiAddrs | string[] | | if passed, use this instead of peerStore & DHT |
| id | string | v | document id or did |
| chainId | number | v | chain id of network on which document is provided |
| nftAddress | string | v | address of nft token |
#### Request
```json
{
"command": "validateDDO",
"node": "PeerId",
"id": "did:op:123",
"chainId": 123,
"nftAddress": "0x123"
}
```
---
## File Info
### `HTTP` POST /directCommand
### `P2P` command: fileInfo
#### Description
returns file information
#### Parameters
| name | type | required | description |
| --------- | ------ | -------- | ---------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| type | string | | type of storage `url or arweave or ipfs` |
| did | string | | document id or did |
| serviceId | number | | service id of services list |
| fileIndex | number | | file index in files array |
| file | object | | file data |
| checksum | number | | index in transaction events list |
> **ON-07 (raw-`file` path):** a raw `file` object needs **no signature or auth token** — it only
> returns metadata of a URL the caller already supplied. Caller-supplied `file.headers` are
> filtered to the allow-list (`accept`, `accept-encoding`, `range`, `content-type`, extended by
> `FILEINFO_ALLOWED_HEADERS`) and the path can be throttled independently via
> `FILEINFO_MAX_REQ_PER_MINUTE`. The `did` + `serviceId` path is unchanged (DDO-based access
> control).
#### Request
```json
{
"command": "fileInfo",
"node": "PeerId",
"type": "123",
"did": "did:op:123",
"serviceId": 123,
"fileIndex": 123,
"file": 123,
"checksum": 123
}
```
#### Response
```
[
{
valid: true
contentLength: "123"
contentType: "123"
name: "123"
type: "url or arweave or ipfs"
}
]
```
---
## Re-Index Transaction
### `HTTP` POST /directCommand
### `P2P` command: reIndex
#### Description
returns a message about successful addition to the reindexing queue
#### Parameters
| name | type | required | description |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| txId | string | v | id of transaction for reindexing |
| chainId | number | v | chain id of network on which transaction is provided |
| eventIndex | number | | index in transaction events list |
#### Request
```json
{
"command": "reIndex",
"node": "PeerId",
"txId": "0x123",
"chainId": 123,
"eventIndex": 123
}
```
#### Response
```
Added to reindex queue successfully
```
---
## Get Fees
### `HTTP` POST /directCommand
### `P2P` command: getFees
#### Description
returns calculated provider fees for DDO with service id
#### Parameters
| name | type | required | description |
| --------- | ------ | -------- | ------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| ddo | object | v | document object |
| serviceId | string | v | service id of services list |
#### Request
```json
{
"command": "getFees",
"node": "PeerId",
"ddo": {
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
"...": "..."
},
"serviceId": "123"
}
```
#### Response
```
[
{
providerFeeAddress: "0x123",
providerFeeToken: "0x123",
providerFeeAmount: 123,
providerData: "0x123",
v: 123,
r: "0x123",
s: "0x123",
validUntil: 123,
}
]
```
---
## Find DDO
### `HTTP` POST /directCommand
### `P2P` command: findDDO
#### Description
returns list of providers from which ddo can be obtained
#### Parameters
| name | type | required | description |
| ------- | ------ | -------- | ------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| id | string | v | document id or did |
#### Request
```json
{
"command": "findDDO",
"node": "PeerId",
"id": "did:op:123"
}
```
#### Response
```
[
{
provider: "PeerId",
id: "did:op:123"
lastUpdateTx: "123",
lastUpdateTime: "123",
}
]
```
---
## Auth Tokens
### `HTTP` POST /api/services/auth/token
### `P2P` command: createAuthToken
#### Description
Mints a JWT auth token, re-usable in place of a per-request signature. The token's authority is the
embedded **consumer signature** over the create-auth-token message (re-verified on every node), not
`JWT_SECRET`.
A token can be **self-limited** along three axes, all folded into the signed message so no
intermediary can broaden them (a stolen "download-only token for node B" cannot be replayed as
compute on node C):
- **audience** — list of node peerIds the token may be used at (omitted ⇒ any node).
- **scope** — list of protocol-command names the token may perform (omitted ⇒ any command).
- **validUntil** — absolute expiry (epoch ms). Capped by `MAX_TOKEN_LIFETIME`; the node **rejects**
(never clamps) an over-cap value. A request with no `validUntil` gets a server-set default expiry
of `createdAt + MAX_TOKEN_LIFETIME` (no never-expiring tokens).
Providing any of `audience` / `scope` / `validUntil` makes it a **v2** token: `validUntil` is then
**required** and must be signed. Omit a field for "unrestricted"; an explicit `[]` is rejected.
`decryptDDO` and mutating-admin commands are **not** allowed in `scope` (and reject tokens entirely
at consumption — they require a fresh request signature). `fetchConfig` / `getLogs` (read-only admin)
are scopable.
The signed message for a v2 token is:
```
address + nonce + "createAuthToken" + issuerPeerId
+ "|v:2"
+ "|aud:" + sort(dedup(audience)).join(",")
+ "|cmd:" + sort(dedup(scope)).join(",")
+ "|exp:" + validUntil
```
(omitted audience/scope ⇒ empty segment). A legacy request (none of the three fields) signs the
byte-identical `address + nonce + "createAuthToken" + issuerPeerId`.
#### Parameters
| name | type | required | description |
| ---------- | -------- | -------- | ------------------------------------------------------------------ |
| address | string | v | consumer address |
| signature | string | v | consumer signature over the message above |
| nonce | string | v | nonce |
| validUntil | number | (v2) | epoch ms; required whenever audience/scope is set |
| audience | string[] | | node peerIds the token may be used at; omit for unrestricted |
| scope | string[] | | protocol-command names the token may perform; omit for unrestricted |
| chainId | string | | chain id for smart-account (ERC-1271) signature validation |
#### Response
```json
{ "token": "eyJ..." }
```
---
## Status
### `HTTP` POST /directCommand
### `P2P` command: status
#### Description
returns status of node
#### Parameters
| name | type | required | description |
| --------------- | ------ | -------- | --------------------------------------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| clientChallenge | string | | OJ-03: when present, the node returns `signedChallenge` proving its peerId (below) |
#### Request
```json
{
"command": "status",
"node": "PeerId",
"clientChallenge": "a-fresh-random-hex-string"
}
```
#### OJ-03 — authenticated issuer identity
When a `clientChallenge` is supplied, the response includes `signedChallenge`: the node's **libp2p
identity-key** signature (0x-hex) over `utf8("ocean-node-status-challenge-v1:" + clientChallenge)`.
A client verifies it against the public key embedded in the node's `id` (peerId) to prove the
endpoint controls the key its peerId commits to — defeating a malicious endpoint that spoofs another
node's peerId (used by ocean.js before minting an auth token). The challenge-signing path has its own
rate limit (`STATUS_CHALLENGE_RATE_LIMIT`). This proves **identity**, not confidentiality — use TLS
(HTTP) / Noise (P2P) so a relay cannot skim the issued token. `signedChallenge` is computed per
request and is never cached.
#### Auth-token policy (`authTokenPolicy`)
The response also carries a static `authTokenPolicy` block so clients know what the node
requires/accepts before minting or presenting an auth token:
```json
{
"authTokenPolicy": {
"maxTokenLifetime": 86400,
"crossNode": "disabled",
"revocationFallback": "cache",
"softFailGrace": 300,
"challengeSupported": true
}
}
```
- `maxTokenLifetime` (seconds) — clients cap `validUntil` to this.
- `crossNode` — `disabled` (self-issued tokens only) or `allowlist` (foreign tokens honored only from
`trustedIssuers`, which is then also present).
- `revocationFallback` — `closed` | `cache` | `open` (behaviour when a token's issuer is unreachable);
`softFailGrace` (seconds) is present only in `cache` mode.
- `challengeSupported` — the node implements the `clientChallenge` / `signedChallenge` proof.
#### Response
```
{
"id": "PeerId",
"publicKey": "0x123",
"address": "0x123",
"version": "123",
"http": true,
"p2p": true,
"provider": [],
"indexer": [],
"supportedStorage": {
"ipfs": true
"arwave": true
"url": true
},
"escrowAddress": {
"8996": "0x123"
},
"subsidyProviders": {
"8996": ["0x123", "0x456"]
},
"subsidyProviderFilter": false,
"uptime": 123,
"platform": {
"cpus": "123",
"freemem": 123,
"totalmem": 123,
"loadavg": [123],
"arch": "123",
"machine": "123",
"platform": "123",
"release": "123",
"osType": "123",
"osVersion": "123",
"node": "123"
}
}
```
`escrowAddress` and `subsidyProviders` are per-chain maps (keyed by chainId). `subsidyProviders`
reflects the node's `SUBSIDY_PROVIDERS` configuration — the Subsidy Provider contract addresses the
node passes to the escrow at **lock and claim** time (lock-time "prepaid" sponsorship and claim-time
"refund" sponsorship); it is `{}` when none are configured. Both are present in
the normal and detailed status. `subsidyProviderFilter` reflects the node's
`SUBSIDY_PROVIDER_FILTER` setting: when `true`, a user-supplied `subsidyProviders` list on a
compute/service request is restricted to addresses already in this map for the request's chain
(see the per-request `subsidyProviders` field below).
### Per-request `subsidyProviders`
`startCompute` (paid), `serviceStart`, and `serviceExtend` accept an optional top-level
`subsidyProviders` field: a plain array of Subsidy Provider contract addresses for the request's
payment chain. The node hands the **same** list to both the escrow lock (lock-time "prepaid"
sponsorship) and the later claim (claim-time "refund" sponsorship). It overrides the node's
`SUBSIDY_PROVIDERS` for that request only:
- **omitted / `undefined`** → the node's configured `SUBSIDY_PROVIDERS` for the chain are used.
- **`[]`** (empty array) → the lock/claim are made with **no** subsidy providers (plain payer-funded).
- **non-empty array** → the lock/claim use **only** these addresses, ignoring node config.
Every address must be a valid EVM address (otherwise HTTP 400). Duplicates are collapsed, and the
list may name at most **10 unique** providers (the escrow's `maxSponsorsPerLock()`); more is rejected
with HTTP 400. When the node has `SUBSIDY_PROVIDER_FILTER` enabled, every supplied address must also
be in the node's `SUBSIDY_PROVIDERS` for that chain, or the request is rejected with HTTP 400 (an
empty array is always allowed). Free compute has no escrow lock/claim, so the field is ignored there.
---
## Query DDO
### `HTTP` POST /directCommand
### `P2P` command: query
#### Description
returns search result for query
#### Parameters
| name | type | required | description |
| -------------- | ------ | -------- | ------------------------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| query | object | v | query parameters |
| query.q | object | v | text to search for in database |
| query.query_by | object | v | one or more field names that should be queried against |
#### Request
```json
{
"command": "query",
"node": "PeerId",
"query": {
"q": "0x123",
"query_by": "nftAddress"
}
}
```
#### Response
```
[{
"facet_counts": [],
"found": 1,
"out_of": 1,
"page": 1,
"request_params": {
"collection_name": "ddo",
"per_page": 10,
"q": "0x123"
},
"search_time_ms": 1,
"hits": [
{
"highlights": [
{
"field": "nftAddress",
"snippet": "0x123",
"matched_tokens": ["0x123"]
}
],
"document": {
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
},
"text_match": 130916
}
]
}]
```
---
## Get DDO
### `HTTP` POST /directCommand
### `P2P` command: getDDO
#### Description
returns document by id
#### Parameters
| name | type | required | description |
| ------- | ------ | -------- | ------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| id | string | v | document id or did |
#### Request
```json
{
"command": "getDDO",
"node": "PeerId",
"id": "did:op:123"
}
```
#### Response
```
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
}
```
---
## Encrypt
### `HTTP` POST /directCommand
### `P2P` command: encrypt
#### Description
returns encrypted blob
#### Parameters
| name | type | required | description |
| -------------- | ------ | -------- | ------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| blob | string | v | blob data |
| encoding | string | v | data encoding `string or base58` |
| encryptionType | string | v | encrypt method `AES or ECIES` |
#### Request
```json
{
"command": "encrypt",
"node": "PeerId",
"blob": "123",
"encoding": "0x123",
"encryptionType": "0x123"
}
```
#### Response
```
0x123
```
---
## Nonce
### `HTTP` POST /directCommand
### `P2P` command: nonce
#### Description
returns stored nonce for an address
#### Parameters
| name | type | required | description |
| ------- | ------ | -------- | ------------------------------------ |
| command | string | v | command name |
| node | string | | if not present it means current node |
| address | string | v | consumer address |
#### Request
```json
{
"command": "nonce",
"node": "PeerId",
"address": "0x123"
}
```
#### Response
```
123
```
---
## Decrypt DDO
### `HTTP` POST /directCommand
### `P2P` command: decryptDDO
#### Description
returns decrypted document
#### Parameters
| name | type | required | description |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| decrypterAddress | string | v | decrypter address |
| chainId | number | v | chain id of network on which document is provided |
| transactionId | string | | tx id of encrypted document |
| dataNftAddress | string | | address of nft token |
| encryptedDocument | string | | encrypted document |
| flags | number | | metadata flags if DDO is ECIES encrypted or lzma compressed |
| documentHash | string | | hash based on sha256 of asset |
| nonce | string | v | is required to verify a request paired with a signature |
| signature | string | v | signed message (see below) |
> **ON-02 signed-message format (BREAKING, since Ocean Node v4.8.0).** Same bound message as the
> HTTP `/api/services/decrypt` endpoint:
>
> ```
> decrypterAddress + nonce + "decryptDDO" + issuerPeerId + chainId + transactionId + dataNftAddress
> ```
>
> Over P2P the `issuerPeerId` is the peerId of the node the command is sent to (the destination),
> which is already known. See the HTTP decrypt section above for the full rationale.
#### Request
```json
{
"command": "decryptDDO",
"node": "PeerId",
"decrypterAddress": "0x123",
"chainId": 123,
"transactionId": "0x123",
"dataNftAddress": "0x123",
"encryptedDocument": "0x123",
"flags": 1,
"documentHash": "0x123",
"nonce": "123",
"signature": "0x123"
}
```
#### Response
```
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.0",
"chainId": 1,
"nftAddress": "0x123",
...
}
```
---
## Download
### `HTTP` POST /directCommand
### `P2P` command: download
#### Description
returns a file stream of the requested file
#### Parameters
| name | type | required | description |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| fileIndex | number | v | file index in the list of document files |
| documentId | string | v | document id or did |
| serviceId | string | v | service id of array of services defining access to the asset |
| transferTxId | string | v | tx id of transaction for approval of datatokens transfer given to the provider's account |
| nonce | string | v | is required to verify a request paired with a signature |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message based on `did + nonce` |
| aes_encrypted_key | string | | encrypted key for cipher to decrypt file |
#### Request
```json
{
"command": "download",
"node": "PeerId",
"fileIndex": 0,
"documentId": "did:op:123",
"serviceId": "0",
"transferTxId": "0x123",
"nonce": "123",
"consumerAddress": "0x123",
"signature": "0x123",
"aes_encrypted_key": "0x123"
}
```
#### Response
```
byte array
```
---
## Get indexing queue
### `HTTP` GET /api/services/indexQueue
#### Description
returns the current indexing queue, as an array of objects
#### Response
```
{
queue: []
}
```
## PolicyServer Passthrough
### `HTTP` POST /api/services/PolicyServerPassthrough
### `P2P` command: PolicyServerPassthrough
#### Description
Forwards request to PolicyServer (if any).
This endpoint is not authenticated. The node forwards the caller-supplied payload and adds
the resolved `ddo` plus its own `nodeAddress`. Caller-supplied identity fields are not
verified.
#### Parameters
| name | type | required | description |
| ----------------------- | ------ | -------- | ---------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| policyServerPassthrough | object | v | command and params for PolicyServer (see docs) |
#### HTTP Example
```json
{
"policyServerPassthrough": {
"action": "newDDO",
"rawDDO": {},
"chainId": 1,
"txId": "0x123",
"eventRaw": "raw event data"
}
}
```
#### P2P Example
```json
{
"command": "PolicyServerPassthrough",
"node": "PeerId",
"policyServerPassthrough": {
"action": "newDDO",
"rawDDO": {},
"chainId": 1,
"txId": "0x123",
"eventRaw": "raw event data"
}
}
```
#### Responses
| code | description |
| ---- | --------------------------------------------------------------- |
| 200 | PolicyServer allowed the request; its response body is returned |
| 400 | missing/invalid parameters |
---
## initializePSVerification
### `HTTP` POST /api/services/initializePSVerification
### `P2P` command: PolicyServerInitialize
#### Description
Asks the PolicyServer to start a verification flow (`initiate` action) for a given
asset/service and consumer. This endpoint requires an `Authorization` header or a
`nonce` + `signature` pair.
This is a distinct command from `PolicyServerPassthrough`, so the signed message uses its
own command string: `consumerAddress + nonce + "PolicyServerInitialize"`.
The verified `consumerAddress` is the one forwarded to the PolicyServer; the caller's
`authorization`, `nonce` and `signature` are added to the `policyServer` object.
#### Parameters
| name | type | required | description |
| --------------- | ------ | -------- | ---------------------------------------------------- |
| documentId | string | v | the asset DID |
| serviceId | string | v | the service id within the asset |
| consumerAddress | string | v | the caller's address |
| policyServer | any | v | free-form data passed to the PolicyServer |
| nonce | string | | required unless an `Authorization` token is supplied |
| signature | string | | required unless an `Authorization` token is supplied |
#### HTTP Example
```json
{
"documentId": "did:op:1234",
"serviceId": "0",
"consumerAddress": "0x9876543210fedcba9876543210fedcba98765432",
"nonce": "1",
"signature": "0x123",
"policyServer": {}
}
```
#### Responses
| code | description |
| ---- | --------------------------------- |
| 200 | PolicyServer response body |
| 400 | missing/invalid parameters |
| 401 | missing or invalid authentication |
| 404 | asset not found |
| 503 | DDO database not available |
---
## Fetch Config
### `HTTP` GET /api/admin/config
#### Description
returns current node configuration with sensitive data hidden (admin only)
`fetchConfig` is a **read-only admin command**, so in addition to a signature it also accepts a scoped
**auth token** in the `Authorization` header (scope it to `fetchConfig`). The `ALLOWED_ADMINS` gate
still applies to the token's authenticated address. (Mutating admin commands reject tokens.)
#### Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| expiryTimestamp | number | v | expiry timestamp for the request |
| signature | string | (v) | signed message — required unless an auth token is sent |
| Authorization | header | | scoped auth token (alternative to signature) |
#### Request
```json
{
"expiryTimestamp": 1234567890,
"signature": "0x123"
}
```
#### Response
```json
{
"keys": {
"privateKey": "[*** HIDDEN CONTENT ***]"
},
"chainIds": [1],
"rpcs": { "1": "https://eth-mainnet.g.alchemy.com/v2/..." },
"...": "..."
}
```
---
## Update Config
### `HTTP` POST /api/admin/config/update
#### Description
updates node configuration and reloads it gracefully (admin only)
#### Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| expiryTimestamp | number | v | expiry timestamp for the request |
| signature | string | v | signed message to authenticate admin request |
| config | object | v | partial configuration object with fields to update |
#### Request
```json
{
"expiryTimestamp": 1234567890,
"signature": "0x123",
"config": {
"chainIds": [1],
"rpcs": { "1": "https://eth-mainnet.g.alchemy.com/v2/..." }
}
}
```
#### Response
```json
{
"keys": {
"privateKey": "[*** HIDDEN CONTENT ***]"
},
"chainIds": [1],
"rpcs": { "1": "https://eth-mainnet.g.alchemy.com/v2/..." },
"...": "..."
}
```
---
## Maintenance (drain) mode
Maintenance mode is an intermediate state between "running normally" and `stopNode` (immediate
process kill). While it is ON, the node:
- **Rejects new commitment**: `startCompute`, `freeStartCompute`, `initializeCompute`,
`serviceStart`, `serviceExtend` are rejected (see the error contract below).
- **Keeps serving already-committed work**: `getComputeStatus`, `getComputeResult`,
`getComputeStreamableLogs`, `stopCompute`, `serviceGetStatus`, `serviceGetResult`,
`serviceStop`, `serviceGetStreamableLogs`, `serviceRestart` all keep working.
- **Everything else is unchanged**: download, DDO query/validate, indexer, P2P, admin, fees,
nonce, persistent storage, access lists, escrow events, auth tokens.
The flag is persisted in the SQLite config DB, so it is **sticky across restarts**: a node that
reboots while in maintenance comes back up still in maintenance and will not accept new work
until an admin disables it. It can also be set at boot with the `MAINTENANCE_MODE` env var (see
`docs/env.md`). There is **no TTL and no auto-exit**: reaching zero running jobs does nothing on
its own — an admin reads the running counts in `status` to decide it is safe to reboot, then
explicitly disables maintenance (or stops the node).
#### Rejection error contract
Rejected requests return HTTP **`503 Service Unavailable`** with a stable machine-readable code
in the JSON response body:
```json
{ "error": "Node is in maintenance mode; not accepting new compute or service requests", "code": "MAINTENANCE_MODE" }
```
> **Important:** `503` is also returned by these handlers for other reasons (e.g.
> `"Compute engines not configured"`). Clients MUST discriminate on the `code` field
> (`"MAINTENANCE_MODE"`), not on the status code alone. The same `code` is also carried in the
> P2P status frame for node-to-node requests, and the REST routes
> (`/api/services/compute`, `/freeCompute`, `/initializeCompute`, `/serviceStart`,
> `/serviceExtend`) return the same `{ "error": ..., "code": ... }` JSON body.
> **Timing note (inherent to the design):** maintenance gates each request independently. A
> client can call `initializeCompute` and pay/authorize an order a moment before an admin
> enables maintenance, then have the follow-up `startCompute` rejected with `MAINTENANCE_MODE`.
> The node creates no new order itself in that window, but a client that already has a valid,
> unused order should retry `startCompute` on another provider rather than treating the
> rejection as fatal. Note that an order can only be reused on another provider whose compute
> environment resolves to the **same on-chain `consumerAddress`** the order was created for; if
> no such provider is available, the client should wait until maintenance ends or obtain a new
> order for the alternative environment.
### `HTTP` POST /api/admin/maintenance
### `HTTP` POST /directCommand
### `P2P` command: setMaintenance
#### Description
Toggles maintenance mode (admin only). Signed with the standard admin fields and gated by
`ALLOWED_ADMINS` / `ALLOWED_ADMINS_LIST`.
#### Parameters
| name | type | required | description |
| --------- | ------- | -------- | ------------------------------------------------ |
| command | string | POST /directCommand | command name (`setMaintenance`) |
| enabled | boolean | v | `true` enables maintenance, `false` disables it |
| nonce | string | v | request nonce |
| address | string | v | admin address |
| signature | string | v | signed message to authenticate the admin request |
#### Request (POST /api/admin/maintenance)
```json
{
"enabled": true,
"nonce": "1700000000000",
"address": "0xAdminAddress",
"signature": "0x..."
}
```
#### Request (POST /directCommand)
```json
{
"command": "setMaintenance",
"enabled": true,
"nonce": "1700000000000",
"address": "0xAdminAddress",
"signature": "0x..."
}
```
#### Response
```json
{ "maintenance": true }
```
### Status visibility
Both `status` and `detailedStatus` expose a `maintenance` object. `enabled` is always present
(the signal clients/dashboards read). The drain-visibility counts are populated for
`detailedStatus` only, so an admin can tell when the node has finished draining:
```json
{
"...": "...",
"maintenance": {
"enabled": true,
"runningComputeJobs": 2,
"runningServices": 1,
"latestExpectedEndTime": 1700003600
}
}
```
| field | type | status level | description |
| ----------------------- | ------- | ------------ | ----------------------------------------------------- |
| `enabled` | boolean | always | whether the node is in maintenance mode |
| `runningComputeJobs` | number | detailed | compute jobs still holding resources |
| `runningServices` | number | detailed | service-on-demand jobs still running |
| `latestExpectedEndTime` | number | detailed | max job/service end time (unix seconds), the drain ETA |
---
## Get Escrow Events
### `HTTP` GET /api/services/escrow/events?
### `HTTP` POST /directCommand
### `P2P` command: getEscrowEvents
#### Description
Returns indexed Escrow contract events. The indexer matches Escrow logs by topic hash, verifies they came from the chain's `Escrow` contract (`Deposit`/`Withdraw`/`Lock` are generic signatures), and stores one row per event in the append-only `escrow` collection keyed by `${txHash}-${logIndex}`. All filters are optional.
#### Parameters
| name | type | required | description |
| ----------- | ------- | --------- | --------------------------------------------------------- |
| command | string | POST only | command name (`getEscrowEvents`) |
| chainId | number | | chain id |
| eventType | string | | one of `Auth, Lock, ReLock, Claimed, Canceled, Deposit, Withdraw, Subsidized, LockSponsored, SponsorRefunded` |
| payer | string | | payer address (case-insensitive) |
| payee | string | | payee address (case-insensitive) |
| token | string | | token address (case-insensitive) |
| provider | string | | subsidy/sponsor provider address (case-insensitive) |
| contract | string | | Escrow contract address |
| reclaimable | boolean | | filter `SponsorRefunded` rows by their reclaimable flag |
| jobId | string | | compute job id |
| txId | string | | transaction hash |
| ranges | object | POST only | range filters keyed by field (see below) |
| offset | number | | rows to skip (default 0) |
| size | number | | page size (default 100, max 250) |
No authentication is required (both the HTTP route and the P2P command are public reads).
#### Range filters
Any field above is an exact-match filter. Numeric fields also support range filtering.
- **Over P2P / `POST /directCommand`**: use the `ranges` object, keyed by record field, where each
value is `{ "min"?, "max"?, "gt"?, "lt"? }` (`min`/`max` inclusive, `gt`/`lt` exclusive). Bounds
may be strings or numbers; uint256 values are compared as big integers, so pass them as strings.
- **Over HTTP GET**: use `Min` / `Max` query params (e.g.
`?blockMin=100&blockMax=200&subsidyAmountMin=1000`).
Range-filterable fields:
| field | pushed to store? |
| ----------------------------------------------------------------------------------------- | ---------------- |
| `block`, `chainId` | yes (native numeric) |
| `amount`, `subsidyAmount`, `bonusAmount`, `oldAmount`, `newAmount`, `maxLockedAmount`, `maxLockSeconds`, `maxLockCounts`, `expiry`, `newExpiry`, `expiryTimestamp` | no — filtered node-side with BigInt comparison over paginated store results (bounded scan; a highly selective amount range over a very large result set may be truncated) |
A range on any field not in this list (e.g. an address field) is rejected with `400`.
#### Request (POST /directCommand)
```json
{
"command": "getEscrowEvents",
"chainId": 8996,
"eventType": "Subsidized",
"provider": "0xabc...",
"ranges": {
"block": { "min": 100, "max": 500 },
"subsidyAmount": { "min": "1000000000000000000" }
},
"offset": 0,
"size": 50
}
```
#### Request (HTTP GET)
```
GET /api/services/escrow/events?chainId=8996&eventType=Subsidized&provider=0xabc...&blockMin=100&blockMax=500&subsidyAmountMin=1000000000000000000&size=50
```
#### Response
Every row has `id, eventType, chainId, contract, block, txHash` plus event-specific fields (`payer, payee, token, jobId, amount, expiry, proof, maxLockedAmount, maxLockSeconds, maxLockCounts`). An `Auth` row additionally carries `expiryTimestamp` (Escrow v2: `0` = indefinite, otherwise the unix ts after which the payee can no longer create/extend locks). A `Subsidized` row (emitted once per contributing Subsidy Provider at claim time) additionally carries `provider, subsidyAmount, bonusAmount`. Escrow v2 lock-time sponsorship adds two events, each emitted once per contributing provider: a `LockSponsored` row (a provider pre-funds a lock at `createLock`) carries `provider, amount`; a `SponsorRefunded` row (unused sponsored tokens returned on partial claim / expiry / reLock-shrink) carries `provider, amount, reclaimable` (`reclaimable: true` ⇒ the push to the provider failed and the amount is parked for the provider to `sweepReclaimable`).
```json
[
{
"id": "0x39f3...6575-3",
"eventType": "Deposit",
"chainId": 8996,
"contract": "0x282d...a1a1",
"block": 55,
"txHash": "0x39f3...6575",
"payer": "0xbe54...ab5e",
"token": "0x282d...a1a1",
"amount": "100000000000000000000"
}
]
```
---
## Get Node Metrics
### `HTTP` GET /nodeMetrics
### `HTTP` POST /directCommand
### `P2P` command: getNodeMetrics
#### Description
Returns a live per-node resource snapshot, rolled up across every C2D engine (the same aggregate the telemetry layer exports) blended with host `os` readings. Read-only, no parameters. `hasAggregate` is a freshness flag: when `false`, no engine had a fresh compute aggregate (metrics collection is disabled via `C2D_METRICS_INTERVAL_SECONDS=0`, or nothing has been sampled yet) and every scalar is a structural zero rather than a genuine reading. The snapshot is returned either way.
#### Parameters
| name | type | required | description |
| ------- | ------ | --------- | ------------------------------- |
| command | string | POST only | command name (`getNodeMetrics`) |
#### Response
```json
{
"collectedAt": 1730370000000,
"hasAggregate": true,
"cpu": {
"usagePercent": 42.5,
"coresAllocated": 4,
"hostCores": 16,
"throttledCount": 0,
"loadAverage": [1.2, 1.1, 0.9]
},
"memory": {
"usedBytes": 2147483648,
"limitBytes": 8589934592,
"hostFreeBytes": 12000000000,
"hostTotalBytes": 34359738368
},
"disk": { "usedBytes": 1073741824 },
"network": { "rxBytes": 12345, "txBytes": 6789 },
"jobs": { "running": 1, "runningFree": 0, "queued": 0, "queuedFree": 0 },
"gpu": [
{
"resourceId": "0",
"vendor": "nvidia",
"utilizationPercent": 55,
"memoryUsedBytes": 2000000000,
"memoryTotalBytes": 16000000000,
"temperatureC": 61,
"powerWatts": 120
}
],
"env": [{ "env": "env-hash", "resource": "cpu", "total": 16, "inUse": 4 }],
"meta": { "sampledContainers": 1, "oldestSampleAgeSeconds": 8 }
}
```
---
## Get Node Metrics History
### `HTTP` GET /nodeMetrics/history?startTime=&stopTime=
### `HTTP` POST /directCommand
### `P2P` command: getNodeMetricsHistory
#### Description
Returns ordered hourly averages of the per-node resource snapshot, persisted to SQLite by the sampler/roll-up cron jobs and retained for `NODE_METRICS_RETENTION_DAYS` (default 180). Scalars are arithmetic means over the hour's minute-samples; `sampleCount` is how many samples fed each bucket; GPU entries are averaged per `resourceId`, env entries per `env`+`resource`. Requires the node-metrics database (returns `503` when unavailable, e.g. history disabled via `NODE_METRICS_HISTORY_ENABLED=false`).
When the requested range includes the current, in-progress hour, the last bucket is a **live** average computed on the fly from the raw samples collected so far this hour (before the top-of-hour roll-up has stored it). It is flagged `"partial": true` and is the only bucket that carries that flag; every completed hour is a finalized, stored average. This lets a caller see fresh data without waiting for the hourly roll-up.
#### Parameters
| name | type | required | description |
| --------- | ------------- | -------- | ---------------------------------------------------------------------------------- |
| command | string | POST only | command name (`getNodeMetricsHistory`) |
| startTime | number/string | | range start — epoch ms or ISO-8601. Defaults to now minus the retention window |
| stopTime | number/string | | range end — epoch ms or ISO-8601. Defaults to now |
`startTime` must be earlier than `stopTime` (else `400`); the range is clamped to the retention window and the row count is capped.
#### Request (POST /directCommand)
```json
{
"command": "getNodeMetricsHistory",
"startTime": 1727778000000,
"stopTime": 1730370000000
}
```
#### Response
```json
{
"startTime": 1727778000000,
"stopTime": 1730370000000,
"count": 1,
"buckets": [
{
"hourStart": 1730368800000,
"sampleCount": 60,
"cpu": { "usagePercent": 40.1, "coresAllocated": 4, "hostCores": 16, "throttledCount": 0 },
"memory": {
"usedBytes": 2000000000,
"limitBytes": 8589934592,
"hostFreeBytes": 12000000000,
"hostTotalBytes": 34359738368
},
"disk": { "usedBytes": 1073741824 },
"network": { "rxBytes": 12000, "txBytes": 6000 },
"jobs": { "running": 1, "runningFree": 0, "queued": 0, "queuedFree": 0 },
"gpu": [{ "resourceId": "0", "vendor": "nvidia", "utilizationPercent": 50 }],
"env": [{ "env": "env-hash", "resource": "cpu", "total": 16, "inUse": 4 }],
"meta": { "sampledContainers": 1 }
}
]
}
```
---
# Compute
For starters, you can find a list of algorithms in the [Ocean Algorithms repository](https://github.com/oceanprotocol/algo_dockers) and the docker images in the [Algo Dockerhub](https://hub.docker.com/r/oceanprotocol/algo_dockers/tags).
## Compute object definitions
### Dataset (`ComputeAsset` Interface)
The `ComputeAsset` interface defines the structure of a compute asset in the Ocean Node. It can include information about the file object, document ID, service ID, transfer transaction ID, and user data.
#### Properties
- **fileObject**: Optional. An object of type `BaseFileObject` representing the file associated with the compute asset.
- **documentId**: Optional. A string representing the document ID of the compute asset.
- **serviceId**: Optional. A string representing the service ID associated with the compute asset.
- **transferTxId**: Optional. A string representing the transaction ID for the transfer of the compute asset.
- **userdata**: Optional. An object containing additional user-defined data related to the compute asset.
```typescript
export interface ComputeAsset {
fileObject?: BaseFileObject
documentId?: string
serviceId?: string
transferTxId?: string
userdata?: { [key: string]: any }
}
```
This interface is used to encapsulate the details of a compute asset, which can be utilized in various compute-related operations within the Ocean Node.
### `ComputeAlgorithm` Interface
The `ComputeAlgorithm` interface defines the structure of a compute algorithm in the Ocean Node.
It can include information about the file object, document ID, service ID, transfer transaction ID, algorithm custom data, metadata and user data.
#### Properties
- **documentId**: Optional. A string representing the document ID of the compute algorithm.
- **serviceId**: Optional. A string representing the service ID associated with the compute algorithm.
- **fileObject**: Optional. An object of type `BaseFileObject` representing the file associated with the compute algorithm.
- **meta**: Optional. An object of type `MetadataAlgorithm` containing metadata related to the compute algorithm.
- **transferTxId**: Optional. A string representing the transaction ID for the transfer of the compute algorithm.
- **algocustomdata**: Optional. An object containing additional custom data related to the compute algorithm.
- **userdata**: Optional. An object containing additional user-defined data related to the compute algorithm.
- **envs**: Optional. Array of keys:values to be used as environment variables for algo.
```typescript
export interface ComputeAlgorithm {
documentId?: string
serviceId?: string
fileObject?: BaseFileObject
meta?: MetadataAlgorithm
transferTxId?: string
algocustomdata?: { [key: string]: any }
userdata?: { [key: string]: any }
}
```
This interface is used to encapsulate the details of a compute algorithm, which can be utilized in various compute-related operations within the Ocean Node.
## Compute commands
### `HTTP` GET /api/services/computeEnvironments
### `P2P` command: getComputeEnvironments
#### Description
fetch all compute environments
#### Response
```json
[
{
"id": "0x7d187e4c751367be694497ead35e2937ece3c7f3b325dcb4f7571e5972d092bd-0xf173fdc0a9c7cc1c34f8aaf6b3aafe866795851b567436e1d4fbab17b0e26ca1",
"runningJobs": 0,
"consumerAddress": "0xf9C5B7eE7708efAc6dC6Bc7d4b0455eBbf22b519",
"platform": { "architecture": "x86_64", "os": "Ubuntu 22.04.3 LTS" },
"fees": { "1": [[{ "feeToken": "0x123", "prices": [{ "id": "cpu", "price": 1 }] }]] },
"storageExpiry": 604800,
"maxJobDuration": 3600,
"minJobDuration": 60,
"minServiceDuration": 60,
"maxServiceDuration": 86400,
"resources": [
{ "id": "cpu", "total": 16, "max": 16, "min": 1, "inUse": 0 },
{
"id": "ram",
"total": 33617674240,
"max": 33617674240,
"min": 1000000000,
"inUse": 0
},
{ "id": "disk", "total": 1000000000, "max": 1000000000, "min": 0, "inUse": 0 }
],
"free": {
"maxJobDuration": 60,
"minJobDuration": 10,
"maxJobs": 3,
"resources": [
{ "id": "cpu", "max": 1, "inUse": 0 },
{ "id": "ram", "max": 1000000000, "inUse": 0 },
{ "id": "disk", "max": 1000000000, "inUse": 0 }
]
},
"runningfreeJobs": 0
}
]
```
`maxJobDuration` / `minJobDuration` apply to **compute jobs**. Services have their own pair,
and SERVICE_START rejects a `duration` outside it:
- `maxServiceDuration` — the ceiling. Defaults to the daemon's
`serviceOnDemand.maxDurationSeconds` and may be **lowered** per environment; a larger per-env
value is clamped to the daemon ceiling at startup. SERVICE_EXTEND also caps the resulting
remaining window to it.
- `minServiceDuration` — the floor. SERVICE_START rejects a shorter `duration`, and
SERVICE_EXTEND rejects a shorter `additionalDuration`: the floor is a minimum *purchase*, so a
smaller one is refused rather than silently billed at the floor. Everything accepted is then
priced by its actual duration, rounded up to whole minutes. Defaults to the environment's own
`minJobDuration`, and may be **raised** per environment; a value below the daemon's
`serviceOnDemand.minDurationSeconds` is clamped up at startup.
Environments on the same engine may therefore report different values for both.
Both fields are additive, and an older node omits them. Their fallbacks differ, so treat each
separately:
- A missing `maxServiceDuration` means the 86400 s (24 h) default — **not** `maxJobDuration`,
which is a different limit and is often much larger, so using it would offer windows the node
rejects.
- A missing `minServiceDuration` means the environment's own `minJobDuration` (raised to the
daemon's `serviceOnDemand.minDurationSeconds`, which itself defaults to 0 — no daemon floor).
That is exactly what such a node already bills a service at.
### `HTTP` POST /api/services/freeCompute
### `P2P` command: freeStartCompute
#### Description
starts a free compute job and returns jobId if succesfull
#### Parameters
| name | type | required | description |
| --------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| command | string | v | command name |
| node | string | | if not present it means current node |
| consumerAddress | string | v | consumer address |
| signature | string | v | signature (msg=String(nonce) ) |
| nonce | string | v | nonce for the request |
| datasets | object | | list of ComputeAsset to be used as inputs |
| algorithm | object | | ComputeAlgorithm definition |
| environment | string | v | compute environment to use |
| resources | object | | optional list of required resources |
| metadata | object | | optional metadata for the job, data provided by the user |
| additionalViewers | object | | optional array of addresses that are allowed to fetch the result |
| queueMaxWaitTime | number | | optional max time in seconds a job can wait in the queue before being started |
| encryptedDockerRegistryAuth | string | | Ecies encrypted docker auth schema for image (see [Private Docker Registries with Per-Job Authentication](../env.md#private-docker-registries-with-per-job-authentication)) |
| output | string | | Ecies encrypted with instructions for uploading compute results (see [C2D result upload to remote storage](../Storage.md#c2d-result-upload-to-remote-storage)) |
| outputBucketId | string | | persistent-storage bucket id; the bucket is mounted at /data/outputs and results are stored there as individual files. Mutually exclusive with `output` (see [persistent storage](../persistentStorage.md#using-a-bucket-for-compute-job-outputs)) |
#### Request
```json
{
"command": "freeStartCompute",
"datasets": [],
"algorithm": {
"meta": { "container": { "image": "ubuntu", "entrypoint": "/bin/bash'" } }
},
"consumerAddress": "0x00",
"signature": "123",
"nonce": 1,
"environment": "0x7d187e4c751367be694497ead35e2937ece3c7f3b325dcb4f7571e5972d092bd-0xbeaf12703d708f39ef98c3d8939ce458553254176dbb69fe83d535883c4cee38",
"resources": [{ "id": "cpu", "amount": 1 }],
"metadata": { "key": "value" }
}
```
#### Response
```json
[
{
"owner": "0x00",
"jobId": "0x7d187e4c751367be694497ead35e2937ece3c7f3b325dcb4f7571e5972d092bd-a4ad237d-dfd8-404c-a5d6-b8fc3a1f66d3",
"dateCreated": "1742291065.119",
"dateFinished": null,
"status": 0,
"statusText": "Job started",
"results": [],
"agreementId": null,
"expireTimestamp": 1742291065.119,
"environment": "0x7d187e4c751367be694497ead35e2937ece3c7f3b325dcb4f7571e5972d092bd-0xf173fdc0a9c7cc1c34f8aaf6b3aafe866795851b567436e1d4fbab17b0e26ca1",
"resources": [
{ "id": "cpu", "amount": 1 },
{ "id": "ram", "amount": 1000000000 },
{ "id": "disk", "amount": 0 }
],
"isFree": true,
"metadata": { "key": "value" }
}
]
```
### `HTTP` GET /api/services/compute
### `P2P` command: getComputeStatus
#### Description
returns job status
#### Parameters
Required at least one of the following parameters:
| name | type | required | description |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| consumerAddress | string | | consumer address to use as filter |
| jobId | string | | jobId address to use as filter |
| agreementId | string | | agreementId address to use as filter |
| includeMetrics | boolean | | override the runtime-metrics default (`true` = require them, `false` = never). See note below. |
| signature | string | | signature over `consumerAddress` + `nonce` + `command` (or an auth token) — authenticates the owner |
| nonce | string | | request nonce, paired with `signature` |
**Runtime metrics are owner-only and returned BY DEFAULT.** If the request carries owner credentials
(`consumerAddress` plus `signature`/`nonce`, or an `Authorization` header token), each job owned by
(or shared with) that address comes back with a `runtimeMetrics` object — no flag needed.
`includeMetrics` only overrides that default:
| `includeMetrics` | behavior |
| --- | --- |
| omitted (default) | Metrics attached when owner credentials are present and valid. A request without credentials — the plain, unauthenticated status call — returns `200` with no metrics, exactly as before. Invalid credentials likewise just mean no metrics. |
| `true` | Metrics are **required**: missing `consumerAddress` answers `400`, failed authentication `401`. Use it when you want to know *why* metrics are absent instead of getting a silently trimmed response. |
| `false` | Metrics are never attached (and the node skips the auth round-trip). |
Metrics never reach a non-owner, and are never part of the on-chain escrow claim proof. They are
best-effort and up to one sampling interval stale (see [compute.md](compute.md) and
`C2D_METRICS_INTERVAL_SECONDS` in [env.md](env.md)).
#### Response
```json
[
{
"owner": "0x00",
"did": null,
"jobId": "a4ad237d-dfd8-404c-a5d6-b8fc3a1f66d3",
"dateCreated": "1742291065.119",
"dateFinished": null,
"status": 0,
"statusText": "Job started",
"results": [],
"inputDID": null,
"algoDID": null,
"agreementId": null,
"expireTimestamp": 1742291065.119,
"environment": "0x7d187e4c751367be694497ead35e2937ece3c7f3b325dcb4f7571e5972d092bd-0xf173fdc0a9c7cc1c34f8aaf6b3aafe866795851b567436e1d4fbab17b0e26ca1",
"resources": [
{
"id": "cpu",
"amount": 1
},
{
"id": "ram",
"amount": 1000000000
},
{
"id": "disk",
"amount": 1000000000
}
],
"isFree": true,
"metadata": { "key": "value" }
}
]
```
When called with owner credentials, each owned job additionally carries a `runtimeMetrics` object
(see [The `runtimeMetrics` object](#the-runtimemetrics-object) below).
---
### The `runtimeMetrics` object
`runtimeMetrics` is an optional snapshot of live container stats, returned on
`COMPUTE_GET_STATUS` / `SERVICE_GET_STATUS` to the **authenticated owner** of the job or service —
by default, without asking for it. It never reaches anyone else, and `includeMetrics=false` opts out.
Clients MUST treat every part as optional and render a field only when present.
**Semantics clients should surface to users:**
- **Best-effort & slightly stale.** Sampled on a fixed cadence (`C2D_METRICS_INTERVAL_SECONDS`,
default 10s), so values can be up to one interval old. `collectedAt` is the sample time — show it
(e.g. "as of 8s ago").
- **May be missing entirely.** No snapshot yet (job just started), collection disabled on the node
(`C2D_METRICS_INTERVAL_SECONDS=0`), or a transient sampling failure ⇒ no `runtimeMetrics` field.
This is normal, not an error.
- **`null` vs absent for GPU numbers.** Inside a `gpu[]` entry, a `null` metric means "the backend
could not read it" — display as "n/a", never as `0`.
- **Bytes are raw bytes**; percentages are rounded to two decimals — memory/disk/GPU are `0–100`,
but CPU `usagePercent` can exceed `100` across multiple cores (see the CPU table); durations are
seconds; the final snapshot after a job/service ends carries the peak/exit values.
#### Top-level fields
| field | type | unit / notes |
| --------------- | ------- | ------------------------------------------------------------------------------------------------ |
| collectedAt | string | ISO-8601 timestamp of the sample |
| containerState | object | see below — status + structured exit info |
| cpu | object | see below |
| memory | object | see below |
| disk | object | see below |
| network | object? | `{ rxBytes, txBytes }`; **absent** when the container runs with no network (`NetworkMode: none`) |
| blockIO | object | `{ readBytes, writeBytes }` — cumulative disk I/O in bytes |
| pids | object | `{ current, limit }` — process/thread count vs the container PID limit (512) |
| gpu | array? | one entry per GPU the job/service holds; **absent** for CPU-only jobs or when GPU metrics are off |
`containerState`:
| field | type | notes |
| ------------ | -------- | ------------------------------------------------------------------------ |
| status | string | e.g. `running`, `exited` |
| startedAt | string? | ISO-8601 |
| finishedAt | string? | ISO-8601; present once the container has stopped |
| exitCode | number? | process exit code (present after exit) |
| oomKilled | boolean | `true` if the kernel OOM-killed the container |
| error | string? | Docker-reported error string, if any |
| restartCount | number | container restarts |
| health | string? | Docker HEALTHCHECK status when the image defines one (e.g. `healthy`) |
`cpu`:
| field | type | unit / notes |
| ---------------------- | ------ | ------------------------------------------------------------------------------- |
| usagePercent | number | % of one host CPU-second per wall-second (docker-stats formula), `0–N×100` |
| allocated | number | CPU cores requested by the job (`0` when unconstrained) |
| usagePercentOfAllocated| number | `usagePercent / allocated` — "how saturated is what you paid for" (`0` if alloc 0)|
| cumulativeSeconds | number | total CPU-seconds consumed since start (monotonic; billing-grade) |
| throttledPeriods | number | CFS quota throttling events — high ⇒ the CPU request is too small |
| throttledSeconds | number | total time throttled, seconds |
`memory`:
| field | type | unit / notes |
| -------------- | ------ | -------------------------------------------------------- |
| usageBytes | number | working-set bytes (`usage − inactive_file`, cgroup v2) |
| limitBytes | number | memory limit (= allocated RAM) in bytes |
| usagePercent | number | `usageBytes / limitBytes × 100` |
| peakUsageBytes | number | max `usageBytes` observed across samples |
`disk`:
| field | type | unit / notes |
| ------------ | ------- | ---------------------------------------------------------------------------------- |
| usedBytes | number | compute jobs: bytes written under `/` (excludes base image); services: writable layer |
| quotaBytes | number? | present only for jobs with a `disk` resource |
| usagePercent | number? | present only when `quotaBytes` is known |
`gpu[]` entry:
| field | type | unit / notes |
| ------------------ | --------------- | --------------------------------------------------------------------- |
| resourceId | string | the requested resource id (`gpu0`, `gpu1`, …) — maps the entry to a device |
| vendor | string | `nvidia` (only NVIDIA is emitted today; `amd`/`intel` reserved) |
| utilizationPercent | number \| null | GPU busy % (`null` = unreadable) |
| memoryUsedBytes | number \| null | VRAM used |
| memoryTotalBytes | number \| null | total VRAM |
| temperatureC | number? | °C, when available |
| powerWatts | number? | current draw, W, when available |
| shared | boolean? | `true` ⇒ device is shareable and the number may include other jobs |
> Note: the node also keeps an internal delta accumulator on the stored snapshot; it is stripped
> from the response and clients will never see it.
#### Example `runtimeMetrics`
```json
{
"collectedAt": "2026-07-29T12:00:10.000Z",
"containerState": {
"status": "running",
"startedAt": "2026-07-29T11:59:30.000Z",
"oomKilled": false,
"restartCount": 0
},
"cpu": {
"usagePercent": 182.4,
"allocated": 2,
"usagePercentOfAllocated": 91.2,
"cumulativeSeconds": 73.1,
"throttledPeriods": 12,
"throttledSeconds": 0.4
},
"memory": {
"usageBytes": 734003200,
"limitBytes": 1073741824,
"usagePercent": 68.36,
"peakUsageBytes": 812345678
},
"disk": { "usedBytes": 524288000, "quotaBytes": 10737418240, "usagePercent": 4.88 },
"network": { "rxBytes": 10485760, "txBytes": 2097152 },
"blockIO": { "readBytes": 41943040, "writeBytes": 8388608 },
"pids": { "current": 24, "limit": 512 },
"gpu": [
{
"resourceId": "gpu0",
"vendor": "nvidia",
"utilizationPercent": 77,
"memoryUsedBytes": 1073741824,
"memoryTotalBytes": 3221225472,
"temperatureC": 55,
"powerWatts": 90
}
]
}
```
### `HTTP` GET /api/services/computeResult
### `P2P` command: getComputeResult
#### Description
Returns the file identified by `index` in the job status `results` array. Select
`type: "output"` for the archive; logs remain separate text files. New job outputs
are ZIP (`outputs.zip`, `application/zip`); historical TAR archives remain readable.
ZIP entries contain the contents of `/data/outputs` without the outer `outputs/`
directory. Regular files and directories are retained; links, special files and unsafe
paths are skipped. Stored ZIP archives support byte-offset downloads over P2P.
Bucket-output jobs have no archive entry; use the persistent storage APIs instead.
Deploy ZIP/TAR-compatible clients before upgraded nodes. Rollback releases must retain
the ZIP/TAR reader so already-published ZIP outputs remain available.
#### Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------------------- |
| consumerAddress | string | v | consumer address to use as filter |
| jobId | string | v | jobId address to use as filter |
| signature | string | v | signature (consumerAddress + jobId + index.toString() + nonce) |
| nonce | string | v | nonce for the request |
| index | number | v | index of result (0 for main result, 1 for logs) |
#### Response
File content
---
## Persistent Storage
### `HTTP` POST /api/services/persistentStorage/buckets
#### Description
Create a new persistent storage bucket. Bucket ownership is set to the request `consumerAddress`.
#### Request Headers
| name | type | required | description |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| Authorization | string | | auth token (optional; depends on node auth configuration) |
#### Request Body
```json
{
"consumerAddress": "0x...",
"signature": "0x...",
"nonce": "123",
"accessLists": []
}
```
#### Response (200)
```json
{
"bucketId": "uuid",
"owner": "0x...",
"accessList": []
}
```
---
### `HTTP` GET /api/services/persistentStorage/buckets
#### Description
List buckets for a given `owner`. Results are filtered by bucket access lists for the calling consumer.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
| chainId | number | v | chain id (used by auth/signature checks) |
| owner | string | v | bucket owner to filter by |
#### Response (200)
```json
[
{
"bucketId": "uuid",
"owner": "0x...",
"createdAt": 1710000000,
"accessLists": []
}
]
```
---
### `HTTP` GET /api/services/persistentStorage/buckets/:bucketId/files
#### Description
List files in a bucket.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
#### Response (200)
```json
[
{
"bucketId": "uuid",
"name": "hello.txt",
"size": 123,
"lastModified": 1710000000
}
]
```
---
### `HTTP` GET /api/services/persistentStorage/buckets/:bucketId/files/:fileName/object
#### Description
Return the `fileObject` for a specific file in a bucket (useful for passing references to other subsystems like compute).
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
#### Response (200)
```json
{
"type": "nodePersistentStorage",
"bucketId": "uuid",
"fileName": "hello.txt"
}
```
---
### `HTTP` GET /api/services/persistentStorage/buckets/:bucketId/files/:fileName
#### Description
Download a file from a bucket. The response body is the raw file bytes. Enforces the bucket
access list (the consumer must be the bucket owner or on the bucket ACL). The same operation is
available as the `persistentStorageDownloadFile` P2P command, which streams the raw bytes back
identically.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
#### Response (200)
Raw file bytes, sent with:
- `Content-Type: application/octet-stream`
- `Content-Disposition: attachment; filename=""`
- `Content-Length` (best-effort)
#### Errors
| status | when |
| ------ | ---------------------------------------------------------- |
| 403 | consumer is not the bucket owner and not on the bucket ACL |
| 404 | file not found in the bucket |
---
### `HTTP` POST /api/services/persistentStorage/buckets/:bucketId/files/:fileName
#### Description
Upload a file to a bucket. The request body is treated as raw bytes.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
#### Request Body
Raw bytes (any content-type).
#### Response (200)
```json
{
"bucketId": "uuid",
"name": "hello.txt",
"size": 123,
"lastModified": 1710000000
}
```
---
### `HTTP` DELETE /api/services/persistentStorage/buckets/:bucketId/files/:fileName
#### Description
Delete a file from a bucket.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | -------------------------------------------------- |
| consumerAddress | string | v | consumer address |
| signature | string | v | signed message (consumerAddress + nonce + command) |
| nonce | string | v | request nonce |
| chainId | number | v | chain id (used by auth/signature checks) |
#### Response (200)
```json
{ "success": true }
```
---
## Service on Demand
Service-on-Demand lets a consumer launch a long-running Docker container (e.g. JupyterLab, a
vLLM inference server, VS Code) on a compute environment, pay up front via on-chain escrow for
a requested `duration`, and reach it over forwarded network endpoints
(`http://:`) while it runs. Unlike a compute job, a service stays up until
it expires, is stopped, or is extended. See [`services.md`](./services.md) for the full design
and security model.
All routes live under `/api/services`. Every command except `serviceTemplates` is
authenticated by a signature over `consumerAddress` + `nonce` + `command` (or an auth-token
`Authorization` header). Cost is computed only from the environment's server-side pricing and
charged to the authenticated `consumerAddress`.
> **Note:** service containers run hardened (`no-new-privileges`, `CapDrop: ['ALL']`), so a
> process inside the container cannot bind to a port below 1024 — have your service listen on a
> **high port** (the published host port is allocated by the node regardless).
### Service object definitions
#### `ServiceTemplatePublic` (returned by `serviceTemplates`)
Operator-published blueprint. Secret `envVars` values are never returned — only their keys via
`envVarKeys`.
| property | type | description |
| --------------------------- | -------- | -------------------------------------------------------- |
| id | string | template id (`[a-z0-9][a-z0-9_-]{0,63}`) |
| name / description | string | human-readable labels |
| image | string | base image |
| tag / checksum / dockerfile | string | image spec — exactly one |
| exposedPorts | number[] | container ports to forward |
| envVarKeys | string[] | keys of operator-set env vars (values never returned) |
| userConfigurableEnvVars | object[] | `{ key, validation?, sensitive? }` passed via `userData` |
| command / entrypoint | string[] | Docker CMD / ENTRYPOINT overrides |
| recommendedResources | object[] | advisory cpu/ram/disk/gpu sizing — see below |
`recommendedResources` is the template's only resource declaration and is **advisory**: the
node does not check it at `serviceStart` — picking an environment and the exact resources to
request is the client's job, and the environment's own `min`/`max`/constraints are what the node
enforces. At most one entry per resource; templates have no `min`. Entry shapes (strict — any
other key, including the retired `min` or a template-level `requiredResources`, makes the node
skip the template with a warning):
- `{ "id": "cpu", "recommended": , "unit": "cores", "description"? }`
- `{ "id": "ram" | "disk", "recommended": , "unit": "GB", "description"? }`
- `{ "kind": "discrete", "type": "gpu", "recommended": 0>, "unit": "GB", "layouts": [...], "gpuCountEnv"?, "description"? }`
`layouts` (1–8 entries, strictly ascending by `gpuCount`) lists every allowed way to place
that VRAM on identical GPUs of one type on one host. Each is `{ "gpuCount": <1..64> }` for one
card — which must itself hold `recommended` (cards are never pooled) — or
`{ "gpuCount": n, "vramPerGpu": }` for `n > 1`; `gpuCount` is exactly the number
of GPUs booked and used, and `gpuCount × vramPerGpu` must be ≥ `recommended`. Each per-card
figure is the smallest card `memoryTotal` the default configuration starts on (memory
utilisation and per-card overhead included), not a GPU class size. Compare against
each GPU's `memoryTotal` from `getComputeEnvironments` (see
[compute.md](compute.md#node-wide-connection-level-resources)). `gpuCountEnv` optionally names
a `userConfigurableEnvVars` key that forces the GPU width at runtime: every layout's `gpuCount`
must pass that key's `validation`, and the key may not also be an operator `envVars` key.
#### `ServiceJob` (returned by start / status / extend / restart / stop)
The encrypted `userData` is never returned. Key fields:
| property | type | description |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| serviceId | string | unique id of the running service |
| environment | string | envId the service runs on |
| owner | string | consumerAddress |
| status | number | `10` Starting, `20` Locking, `11` PullImage, `13` BuildImage, `30` Claiming, `40` Running, `12` PullImageFailed, `14` BuildImageFailed, `15` VulnerableImage, `50` Stopping, `70` Stopped, `75` Expired, `76` DiskQuotaExceeded (restartable/editable like Stopped until expiresAt), `99` Error |
| statusText | string | human-readable status |
| dateCreated | string | ISO timestamp |
| expiresAt | number | Unix ms timestamp when the paid window ends |
| duration | number | requested seconds |
| endpoints | object[] | `{ containerPort, hostPort, url }` per exposed port |
| resources | object[] | `{ id, amount, price }` |
| payment | object | initial start payment record |
| extendPayments | object[] | one entry per successful extend |
---
### `HTTP` GET /api/services/serviceTemplates
### `P2P` command: serviceGetTemplates
#### Description
List the operator-published service templates (sanitized). Not authenticated.
#### Query Parameters
| name | type | required | description |
| ------- | ------ | -------- | -------------------------------------------------- |
| chainId | number | | filter to templates whose envs price on this chain |
#### Response (200)
```json
[
{
"id": "jupyter-cpu",
"name": "JupyterLab (CPU)",
"image": "quay.io/jupyter/datascience-notebook",
"tag": "latest",
"exposedPorts": [8888],
"userConfigurableEnvVars": [{ "key": "JUPYTER_TOKEN", "sensitive": true }],
"recommendedResources": [
{ "id": "cpu", "recommended": 2, "unit": "cores" },
{ "id": "ram", "recommended": 4, "unit": "GB" }
]
}
]
```
---
### `HTTP` POST /api/services/serviceStart
### `P2P` command: serviceStart
#### Description
Validate the request, persist the job, and **return immediately** with the `serviceId` — the
response does **not** wait for escrow or the image pull/build. The consumer supplies the
container spec directly (an `image` referenced by `tag`/`checksum`, or an inline `dockerfile`
when the operator allows building).
The returned job has `status: 10` (`Starting`) and no `endpoints` yet. A background loop then
advances it: `Starting → Locking` (escrow lock) `→ PullImage`/`BuildImage` (image + scan) `→
Claiming` (claim on success, or refund/cancel the lock on failure) `→ Running`. **Poll
`serviceStatus`** until `status` is `40` (`Running`, with `endpoints` populated) or a terminal
`*Failed` / `Error` status. Note that `Running` is not a final resting state for a poller to stop
at: the same background loop keeps checking the container's health afterward, and can move an
already-`Running` service to `Error` later if the container dies on its own — long-lived clients
should keep watching `serviceStatus`, not just stop once they first see `Running`.
#### Request Body
```json
{
"consumerAddress": "0x...",
"nonce": "123",
"signature": "0x...",
"environment": "env-1",
"image": "nginxinc/nginx-unprivileged",
"tag": "alpine",
"exposedPorts": [8080],
"resources": [
{ "id": "cpu", "amount": 1 },
{ "id": "ram", "amount": 1 }
],
"duration": 3600,
"userData": "",
"metadata": { "run": "experiment-7", "attempt": 2 },
"payment": { "chainId": 8996, "token": "0x..." }
}
```
| field | type | required | description |
| ---------------------------- | -------- | -------- | ----------------------------------------------------------------- |
| environment | string | v | envId to run on (services must be enabled on it) |
| image | string | v | base image |
| tag / checksum / dockerfile | string | | image spec — at most one; `dockerfile` requires `allowImageBuild` |
| additionalDockerFiles | object | | filename → content; only with `dockerfile` |
| dockerCmd / dockerEntrypoint | string[] | | container CMD / ENTRYPOINT overrides |
| exposedPorts | number[] | | container ports to publish |
| resources | object[] | | `{ id, amount }` requested resources |
| duration | number | v | seconds; capped by `serviceOnDemand.maxDurationSeconds` |
| userData | string | | ECIES-encrypted (to the node pubkey) JSON of env vars |
| metadata | object | | arbitrary user labels (`string`/`number`/`boolean` values, ≤1 KB JSON); node-opaque. Returned on both `serviceStatus` and `serviceList` |
| payment | object | v | `{ chainId, token }` |
#### Response (200)
The immediate response — `Starting`, no endpoints yet. Poll `serviceStatus` for the rest.
```json
[
{
"serviceId": "0x...",
"environment": "env-1",
"owner": "0x...",
"status": 10,
"statusText": "Starting",
"expiresAt": 1735689600000,
"duration": 3600,
"endpoints": [],
"payment": { "chainId": 8996, "token": "0x...", "cost": 10 }
}
]
```
Errors: `403` services disabled on the env / access denied, `400` invalid params (bad address,
duration, image spec, metadata over 1 KB, unavailable resources, or no pricing for the token).
Escrow lock/claim now
happens in the background, so escrow failures surface as the job ending in an `Error` / `*Failed`
status (observed via `serviceStatus`), not as a synchronous `402`.
---
### `HTTP` GET /api/services/serviceStatus
### `P2P` command: serviceGetStatus
#### Description
Read service job status and endpoints. **Authenticated and owner-scoped** — only services owned
by the authenticated `consumerAddress` are returned.
#### Query Parameters
| name | type | required | description |
| --------------- | ------- | -------- | ----------- |
| consumerAddress | string | v | owner address |
| nonce | string | v | request nonce |
| signature | string | v | signed message (or use an `Authorization` auth-token header) |
| serviceId | string | | filter to a single service; omit to list all owned services |
| includeMetrics | boolean | | runtime metrics (`runtimeMetrics`) are included by default; pass `false` to omit them |
#### Response (200)
Array of `ServiceJob` (with `userData` stripped; any user-supplied `metadata` is kept — this
path is owner-scoped). Each entry also carries a sanitized
`runtimeMetrics` object — see [The `runtimeMetrics` object](#the-runtimemetrics-object) for its full
structure. Included by default here because this command is already authenticated and owner-scoped
(pass `includeMetrics=false` to omit); the node-wide `serviceList` never returns metrics. Metrics are
best-effort (see [compute.md](compute.md) and `C2D_METRICS_INTERVAL_SECONDS` in [env.md](env.md)).
---
### `HTTP` GET /api/services/serviceList
### `P2P` command: serviceList
#### Description
Node-wide service listing. **Authenticated but NOT owner-scoped** — any authenticated
consumer identity sees every owner's services. By default it returns only the services
**currently holding a resource reservation** (exactly what the engines count against the
shared pools): `Running`/`Restarting`/`Stopping`, the mid-start pipeline states, paid
`Error` (container died, restartable), and `Stopped` / `DiskQuotaExceeded` within the paid window.
`Expired` and never-paid jobs hold nothing and are not listed by default.
#### Query Parameters
| name | type | required | description |
| ------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| consumerAddress | string | v | caller identity (any consumer) |
| nonce | string | v | request nonce |
| signature | string | v | signed message (or use an `Authorization` auth-token header) |
| status | number | | filter to ONE specific `ServiceStatusNumber` (any status, incl. `75` Expired); takes precedence over `includeAllStatuses` |
| includeAllStatuses | boolean | | `true` returns services in every status instead of only the resource-holding set |
| fromTimestamp | string | | only services created at/after this moment — ISO date (`2026-01-15T00:00:00Z`) or Unix timestamp (seconds or milliseconds) |
#### Response (200)
Array of `ServiceJob`, **listing-sanitized**: `userData`, `dockerCmd`, `dockerEntrypoint`,
`dockerfile` and `additionalDockerFiles` are stripped (identity, status, resources,
endpoints, payment metadata and the owner's `metadata` are kept). Use the owner-scoped
`serviceStatus` to see a service's own configuration.
---
### `HTTP` POST /api/services/serviceExtend
### `P2P` command: serviceExtend
#### Description
Pay to push the service expiry further out. The total remaining duration must not exceed
`maxDurationSeconds`. Re-checks the environment access list.
#### Request Body
```json
{
"consumerAddress": "0x...",
"nonce": "123",
"signature": "0x...",
"serviceId": "0x...",
"additionalDuration": 1800,
"payment": { "chainId": 8996, "token": "0x..." }
}
```
`additionalDuration` must be a positive number of seconds.
#### Response (200)
The updated `ServiceJob` (advanced `expiresAt`, new entry in `extendPayments`).
---
### `HTTP` POST /api/services/serviceRestart
### `P2P` command: serviceRestart
#### Description
Recreate the service container (no extra charge), keeping the same `expiresAt`, resources and
host ports. Re-checks the environment service gate and access list; rejected if the service has
expired. This is the recommended recovery path after a service lands in `Error` because its
container died on its own (the background health check leaves host ports/network/container
record reserved specifically so restart can reuse them), in addition to recovering from an
explicit `serviceStop` or any other terminal failure.
**Restart is atomic — either all-old or all-new, never a mix of new params over the stored job:**
- **REUSE mode** — the request carries **none** of the container params below. The service
restarts on exactly its stored spec (image, `userData`, `dockerCmd`, `dockerEntrypoint`). Use
this to simply bounce a service back to `Running`.
- **RESPEC mode** — the request carries **any** container param. The container is rebuilt
entirely from the request: `image` becomes **required** and exactly one of `tag`/`checksum`/
`dockerfile` applies (validated exactly like `serviceStart`). `userData`/`dockerCmd`/
`dockerEntrypoint` are taken **as-sent** — anything omitted here is empty/unset, it is **not**
pulled from the stored job. This is the bug-fix flow: publish a fixed image under a new tag,
then restart re-supplying the full spec (e.g. same `image`, new `tag`).
Because `image` is mandatory whenever any container param is present, you cannot ride a new
`userData`/`dockerCmd` on top of the stored image — a partial change is rejected (400). Payment,
resources and duration are always preserved; only the container spec can change. A service whose
start payment was **never claimed** (escrow lock failed or was refunded) cannot be restarted —
start a new service instead.
#### Request Body
REUSE mode (bounce the service on its stored spec):
```json
{
"consumerAddress": "0x...",
"nonce": "123",
"signature": "0x...",
"serviceId": "0x..."
}
```
RESPEC mode (restart on a new image spec — `image` required, plus at most one of
`tag`/`checksum`/`dockerfile`):
```json
{
"consumerAddress": "0x...",
"nonce": "123",
"signature": "0x...",
"serviceId": "0x...",
"image": "myrepo/myservice",
"tag": "v2",
"userData": "",
"dockerCmd": [""],
"dockerEntrypoint": [""]
}
```
| name | type | required | description |
| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| serviceId | string | v | the service to restart |
| image | string | RESPEC | base image name (build label when `dockerfile` is set). Required as soon as any container param is present |
| tag | string | | pull by `name:tag`; mutually exclusive with `checksum`/`dockerfile` |
| checksum | string | | pull by digest `sha256:<64 hex>`; mutually exclusive with `tag`/`dockerfile` |
| dockerfile | string | | build from an inline Dockerfile; requires `allowImageBuild` on the environment; mutually exclusive with `tag`/`checksum` |
| additionalDockerFiles | object | | extra `filename → content` files for the build context (only with `dockerfile`) |
| userData | string | | ECIES-encrypted (to the node public key) JSON → the container's env-var map |
| dockerCmd | string[] | | exact container command (Docker exec-form CMD override) |
| dockerEntrypoint | string[] | | container ENTRYPOINT override |
| metadata | object | | user labels (≤1 KB JSON). **Not** a container param — independent of REUSE/RESPEC. When present it **replaces** the stored metadata; when omitted the original metadata is kept |
#### Response (200)
The `ServiceJob` with a new `containerId` (same `hostPort` and `expiresAt`; the `image`/`tag`/
`checksum`/`dockerfile`/`containerImage` fields reflect the new spec in RESPEC mode).
#### Response (400)
Not found, expired, payment never claimed, metadata over 1 KB, or an invalid respec — a
container param was sent without `image`, or more than one of `tag`/`checksum`/`dockerfile` was
provided.
#### Response (403)
`dockerfile` was supplied but the environment has `allowImageBuild=false`.
---
### `HTTP` POST /api/services/serviceStop
### `P2P` command: serviceStop
#### Description
Tear down the service container and network. Owner-gated. The paid reservation is kept until
`expiresAt`; optional `release: true` ends the paid window now so the expiry sweep frees it
instead — no refund, no restart.
#### Request Body
```json
{
"consumerAddress": "0x...",
"nonce": "123",
"signature": "0x...",
"serviceId": "0x...",
"release": false
}
```
#### Response (200)
The `ServiceJob` with `status: 70` (Stopped). An already disk-stopped service keeps
`status: 76` (`DiskQuotaExceeded`); both states allow RESTART (REUSE or RESPEC) and EXTEND
until `expiresAt`. Only `release: true` ends the paid window early.
---
### `HTTP` GET /api/services/serviceStreamableLogs
### `P2P` command: serviceGetStreamableLogs
#### Description
Stream the service container's stdout/stderr logs live. **Authenticated and owner-scoped**
— only the service's owner (`consumerAddress`, proven by signature/nonce or auth token) can
read its logs. Available while the service is `Running` (`40`) or `Error` (`99`) — a crashed
container is kept around until `stop`/`restart`, so its logs remain fetchable for diagnosis.
#### Query Parameters
| name | type | required | description |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consumerAddress | string | v | owner address |
| nonce | string | v | request nonce |
| signature | string | v | signed message (or use an `Authorization` auth-token header) |
| serviceId | string | v | the service to stream logs for |
| since | string | | lower time bound for returned logs. Either a Unix timestamp in seconds (e.g. `1735689600`), or a relative duration counted back from now (e.g. `30s`, `45m`, `2h`, `7d`). Omit to get the full history since container start, then follow live. |
#### Response (200)
Raw `stdout`/`stderr` byte stream from the container, connection kept open and followed live.
With `since` set, historical output before that point is skipped — useful for a long-lived
service where fetching the full history would otherwise dump days/weeks of buffered logs
before reaching the live tail (e.g. `since=1h` for just the last hour).
#### Response (400)
`since` is present but not a valid Unix timestamp or duration (``).
#### Response (404)
Service not found, or not `Running`/`Error`.
#### Response (401)
Missing/invalid auth, or `consumerAddress` is not the service owner.
---
### `HTTP` GET /api/services/serviceResult
### `P2P` command: serviceGetResult
#### Description
Download a service's `/data/outputs` as a zip, for a service **without** an `outputBucketId`
(see [Service outputs](services.md#service-outputs)). **Authenticated and owner-scoped.**
Either one of the archives the node took when a container of the service was removed
(`index`, as listed in `outputArchives` on `serviceStatus`), or a zip of the running
container's folder (`live=true`).
#### Query Parameters
| name | type | required | description |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| consumerAddress | string | v | owner address |
| nonce | string | v | request nonce |
| signature | string | v | signed message (or use an `Authorization` auth-token header) |
| serviceId | string | v | the service |
| index | number | | archive index from `outputArchives`; required unless `live=true` |
| offset | number | | resume an archive download from this byte (not with `live`) |
| live | boolean | | `true` to zip the running container's `/data/outputs` instead of an archive |
#### Response (200)
`application/zip` stream, with `Content-Disposition: attachment; filename="-outputs-.zip"`
(or `-outputs-live.zip`). An archive download also carries `Content-Length`
(the bytes left after `offset`).
#### Response (400)
Neither `index` nor `live`, both, an invalid `index`/`offset`, `offset` with `live`, a
live download of a service whose outputs go to a bucket, an unknown `serviceId`, or
`consumerAddress` is not the service owner (the same "Service job not found" response
as an unknown `serviceId`).
#### Response (401)
Missing/invalid auth.
#### Response (404)
No archive with that `index` (or it was deleted by storage expiry), or no `/data/outputs`
in the running container.
#### Response (409)
`live=true` while the service has no container (e.g. `Stopped`, `Expired`, mid-restart).
#### Response (416)
`offset` is past the end of the archive.