Skip to main content
API docs by Redocly

Bee API (5.2.0)

Download OpenAPI specification:Download

A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages

Browse the documentation @ the Swarm Docs

Auth

Authenticate - This endpoint is experimental

Authorizations:
basicAuth
Request Body schema: application/json
role
string
expiry
integer

Expiration time in seconds

Responses

Request samples

Content type
application/json
{
  • "role": "string",
  • "expiry": 0
}

Response samples

Content type
application/json
{
  • "key": "string"
}

Refresh the auth token - This endpoint is experimental

Authorizations:
bearerAuth
Request Body schema: application/json
role
string
expiry
integer

Expiration time in seconds

Responses

Request samples

Content type
application/json
{
  • "role": "string",
  • "expiry": 0
}

Response samples

Content type
application/json
{
  • "key": "string"
}

Bytes

Upload data

Authorizations:
None
header Parameters
swarm-postage-batch-id
required
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

swarm-tag
object (SwarmTagParameter)

Associate upload with an existing Tag UID

swarm-pin
object (SwarmPinParameter)

Represents if the uploaded data should be also locally pinned on the node.

swarm-deferred-upload
object (SwarmDeferredUpload)

Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be direct.

swarm-encrypt
object (SwarmEncryptParameter)

Represents the encrypting state of the file

swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get referenced data

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address reference to content

header Parameters
swarm-cache
boolean
Default: true

Determines if the download data should be cached on the node. By default the download will be cached

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieve strategy on redundant data. The numbers stand for NONE, DATA, PROX and RACE, respectively. Strategy NONE means no prefetching takes place. Strategy DATA means only data chunks are prefetched. Strategy PROX means only chunks that are close to the node are prefetched. Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. The default strategy is NONE, DATA, falling back to PROX, falling back to RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Chunk

Upload chunk

Authorizations:
None
header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

Request Body schema: application/octet-stream

Chunk binary data that has to have at least 8 bytes.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Upload stream of chunks

Returns a WebSocket connection on which stream of chunks can be uploaded. Each chunk sent is acknowledged using a binary response 0 which serves as confirmation of upload of single chunk. Chunks should be packaged as binary messages for uploading. If a tag is specified, the chunks will be streamed into local storage and then be uploaded to the network once the stream is closed. If a tag is not specified, the chunks will bypass local storage and be directly uploaded to the network through the stream as they arrive.

Authorizations:
None
header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Get chunk

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of chunk

header Parameters
swarm-cache
object (SwarmCache)

Determines if the download data should be cached on the node. By default the download will be cached

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Check if chunk at address exists locally

Authorizations:
None
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of chunk

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

BZZ

Upload file or a collection of files

In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.

User can also upload a tar file along with the swarm-collection header. This will upload the tar file after extracting the entire directory structure.

If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads.

A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files uploaded as a multipart request, the swarm-index-document header should be used with the name of the file.

Authorizations:
None
query Parameters
name
string (FileName)

Filename when uploading single file

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-pin
boolean

Represents if the uploaded data should be also locally pinned on the node.

swarm-encrypt
boolean

Represents the encrypting state of the file

Content-Type
string

The specified content-type is preserved for download of the asset

swarm-collection
boolean

Upload file/files as a collection

swarm-index-document
string
Example: index.html

Default file to be referenced on path, if exists under that path

swarm-error-document
string
Example: error.html

Configure custom error document to be returned when a specified path can not be found in collection

swarm-deferred-upload
boolean
Default: false

Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be direct.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Request Body schema:
file
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get file or index document from a collection of files

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of content

header Parameters
swarm-cache
boolean
Default: true

Determines if the download data should be cached on the node. By default the download will be cached

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieve strategy on redundant data. The numbers stand for NONE, DATA, PROX and RACE, respectively. Strategy NONE means no prefetching takes place. Strategy DATA means only data chunks are prefetched. Strategy PROX means only chunks that are close to the node are prefetched. Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. The default strategy is NONE, DATA, falling back to PROX, falling back to RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Get referenced file from a collection of files

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of content

path
required
string

Path to the file in the collection.

header Parameters
swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieve strategy on redundant data. The numbers stand for NONE, DATA, PROX and RACE, respectively. Strategy NONE means no prefetching takes place. Strategy DATA means only data chunks are prefetched. Strategy PROX means only chunks that are close to the node are prefetched. Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. The default strategy is NONE, DATA, falling back to PROX, falling back to RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Tag

Get list of tags

Authorizations:
None
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Create Tag

Tags can be thought of as upload sessions which can be tracked using the tags endpoint. It will keep track of the chunks that are uploaded as part of the tag and will push them out to the network once a done split is called on the Tag. This happens internally if you use the Swarm-Deferred-Upload header.

Authorizations:
None
Request Body schema: application/json
address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "split": 0,
  • "seen": 0,
  • "stored": 0,
  • "sent": 0,
  • "synced": 0
}

Get Tag information using Uid

Authorizations:
None
path Parameters
uid
required
integer (Uid)

Uid

Responses

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "split": 0,
  • "seen": 0,
  • "stored": 0,
  • "sent": 0,
  • "synced": 0
}

Delete Tag information using Uid

Authorizations:
None
path Parameters
uid
required
integer (Uid)

Uid

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid

Authorizations:
None
path Parameters
uid
required
integer (Uid)

Uid

Request Body schema: application/json

Can contain swarm hash to use for the tag

address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string",
  • "apiVersion": "0.0.0",
  • "debugApiVersion": "0.0.0"
}

Pinning

Pin the root hash with the given reference

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Unpin the root hash with the given reference

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Get pinning status of the root hash with the given reference

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
Example
"36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"

Get the list of pinned root hash references

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "references": [
    ]
}

Postal Service for Swarm

Send to recipient or target with Postal Service for Swarm

Authorizations:
None
path Parameters
topic
required
string (PssTopic)

Topic name

targets
required
string (PssTargets) ^[0-9a-fA-F]{1,6}(,[0-9a-fA-F]{1,6})*$

Target message address prefix. If multiple targets are specified, only one would be matched.

query Parameters
recipient
string (PssRecipient)

Recipient publickey

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Subscribe for messages on the given topic.

Authorizations:
None
path Parameters
topic
required
string (PssTopic)

Topic name

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Single owner chunk

Upload single owner chunk

Authorizations:
None
path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

id
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Id

query Parameters
sig
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: sig=cf880b8eeac5093fa27b0825906c600685

Signature

header Parameters
swarm-postage-batch-id
required
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

swarm-pin
boolean

Represents if the uploaded data should be also locally pinned on the node.

Request Body schema: application/octet-stream

The SOC binary data is composed of the span (8 bytes) and the at most 4KB payload.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Feed

Create an initial feed root manifest

Authorizations:
None
path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

topic
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic

query Parameters
type
string (FeedType) ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-pin
boolean

Represents if the uploaded data should be also locally pinned on the node.

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Find feed update

Authorizations:
None
path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

topic
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic

query Parameters
at
integer

Timestamp of the update (default: now)

after
integer

Start index (default: 0)

type
string (FeedType) ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Stewardship

Check if content is available

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Root hash of content (can be of any type: collection, file, chunk)

Responses

Response samples

Content type
application/json
{
  • "isRetrievable": true
}

Re-upload content for specified root hash

Authorizations:
None
path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Re-uploads content for specified root hash (can be of any type: collection, file, chunk, etc.)

header Parameters
swarm-postage-batch-id
object (SwarmPostageBatchId)

Postage batch to use for re-upload. If none is provided and the file was uploaded on the same node before, it will re-use the same batch. If not found, it will return error. If a new batch is provided, the chunks are stamped again with the new batch.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Connectivity

Get overlay and underlay addresses of the node

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "overlay": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "underlay": [
    ],
  • "ethereum": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "publicKey": "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4",
  • "pssPublicKey": "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4"
}

Get a list of blocklisted peers

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Connect to address

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
multiAddress
required
string (MultiAddress)

Underlay address of peer

Responses

Response samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get a list of peers

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "peers": [
    ]
}

Remove peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Try connection to node

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "rtt": "5.0018ms"
}

Get topology of known network

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "baseAddr": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "population": 0,
  • "connected": 0,
  • "timestamp": "string",
  • "nnLowWatermark": 0,
  • "depth": 0,
  • "reachability": "Unknown",
  • "networkAvailability": "Unknown",
  • "bins": {
    }
}

Get configured P2P welcome message

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "welcomeMessage": "string"
}

Set P2P welcome message

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
Request Body schema: application/json
welcomeMessage
string

Responses

Request samples

Content type
application/json
{
  • "welcomeMessage": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string",
  • "apiVersion": "0.0.0",
  • "debugApiVersion": "0.0.0"
}

Status

Get node overall health Status

Health Status will indicate node healthiness.

If node is unhealthy please check node logs for errors.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string",
  • "apiVersion": "0.0.0",
  • "debugApiVersion": "0.0.0"
}

Readiness endpoint indicates if node is ready to start accepting traffic

Authorizations:
None

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Get reserve state

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "radius": 0,
  • "storageRadius": 0,
  • "commitment": 0
}

Get chain state

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "chainTip": 0,
  • "block": 0,
  • "totalAmount": "1000000000000000000",
  • "currentPrice": "1000000000000000000"
}

Get information about the node

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "beeMode": "light",
  • "chequebookEnabled": true,
  • "swapEnabled": true
}

Balance

Get the balances with all known peers including prepaid services

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "balances": [
    ]
}

Get the balances with a specific peer including prepaid services

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "balance": "1000000000000000000"
}

Get the past due consumption balances with all known peers

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "balances": [
    ]
}

Get the past due consumption balance with a specific peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "balance": "1000000000000000000"
}

Chequebook

Get the address of the chequebook contract used

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "chequebookAddress": "36b7efd913ca4cf880b8eeac5093fa27b0825906"
}

Get the balance of the chequebook

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "totalBalance": "1000000000000000000",
  • "availableBalance": "1000000000000000000"
}

Get last cashout action for the peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
peer-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "lastCashedCheque": {
    },
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a",
  • "result": {
    },
  • "uncashedAmount": "1000000000000000000"
}

Cashout the last cheque for the peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
peer-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Get last cheques for the peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
peer-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "lastreceived": {
    },
  • "lastsent": {
    }
}

Get last cheques for all peers

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "lastcheques": [
    ]
}

Deposit tokens from overlay address into chequebook

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
query Parameters
amount
required
integer

amount of tokens to deposit

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Withdraw tokens from the chequebook to the overlay address

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
query Parameters
amount
required
integer

amount of tokens to withdraw

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Settlements

Get amount of sent and received from settlements with a peer

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "received": 0,
  • "sent": 0
}

Get settlements with all known peers and total amount sent or received

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "totalReceived": 0,
  • "totalSent": 0,
  • "settlements": [
    ]
}

Get time based settlements with all known peers and total amount sent or received

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "totalReceived": 0,
  • "totalSent": 0,
  • "settlements": [
    ]
}

Transaction

Get list of pending transactions

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "pendingTransactions": [
    ]
}

Get information about a sent transaction

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None
path Parameters
txHash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a",
  • "to": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "nonce": 0,
  • "gasPrice": "1000000000000000000",
  • "gasLimit": 0,
  • "gasTipCap": "1000000000000000000",
  • "gasTipBoost": 0,
  • "gasFeeCap": "1000000000000000000",
  • "data": "string",
  • "created": "2020-06-11T11:26:42.6969797+02:00",
  • "description": "string",
  • "value": "1000000000000000000"
}

Rebroadcast existing transaction

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None
path Parameters
txHash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Cancel existing transaction

This endpoint is available on the main API only if the node is spawned with the --restricted flag.

Authorizations:
None
path Parameters
txHash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Postage Stamps

Get stamps for this node

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "stamps": [
    ]
}

Get an individual postage batch status

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Responses

Response samples

Content type
application/json
Example
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "utilization": 0,
  • "usable": true,
  • "label": "string",
  • "depth": 0,
  • "amount": "1000000000000000000",
  • "bucketDepth": 0,
  • "blockNumber": 0,
  • "immutableFlag": true,
  • "exists": true,
  • "batchTTL": 0
}

Get extended bucket data of a batch

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Responses

Response samples

Content type
application/json
{
  • "depth": 0,
  • "bucketDepth": 0,
  • "bucketUpperBound": 0,
  • "buckets": [
    ]
}

Buy a new postage batch.

Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth
path Parameters
amount
required
string (BigInt)
Example: 1000000000000000000

Amount of BZZ added that the postage batch will have.

depth
required
integer

Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16)

query Parameters
label
string

An optional label for this batch

header Parameters
immutable
boolean
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Top up an existing postage batch.

Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
None
path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Batch ID to top up

amount
required
integer

Amount of BZZ per chunk to top up to an existing postage batch.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Dilute an existing postage batch.

Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
None
path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Batch ID to dilute

depth
required
integer

New batch depth. Must be higher than the previous depth.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Get all globally available batches that were purchased by all nodes.

This endpoint is available on the main API only if the node is spawned with the --restricted flag along with a bearer authentication token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "batches": [
    ]
}