Skip to main content

Blob Operations Quickstart

The core Walrus blob operations, store, read, and check status, work three ways: the Walrus CLI, the HTTP API, and Python. Each operation appears in all three so you can pick the surface that fits your stack, or compare them side by side.

Walrus does not ship a dedicated Python SDK. A Python backend integrates with Walrus through the HTTP API, reading from an aggregator and writing to a publisher, or by driving the walrus CLI as a subprocess. The Python examples use the HTTP API because it needs nothing beyond the requests library.

  • No API key required. The public Walrus aggregator and publisher endpoints are open.
  • Set the endpoints you want to use. The examples on this page use the Testnet endpoints from the Network Reference:
export AGGREGATOR=https://aggregator.walrus-testnet.walrus.space
export PUBLISHER=https://publisher.walrus-testnet.walrus.space
  • Choose a surface and complete the necessary setup:
    • CLI: Install and configure the walrus client. See Getting Started.
    • HTTP API: Any HTTP client, such as curl.
    • Python: Install the requests library with pip install requests.
Public endpoint limits

Public aggregators and publishers limit requests to 10MB, and Walrus does not provide a public unauthenticated publisher on Mainnet. For larger blobs or production Mainnet writes, run your own publisher, use an upload relay, or drive the CLI. See the Mainnet Publisher Production Guide.

How to store a blob​

Store a file for a number of epochs. The store returns a blob ID.

$ walrus store ./report.pdf --epochs 5

How to read a blob​

Read a blob using its blob ID.

$ walrus read <BLOB_ID> --out ./report.pdf

Without the flag --out, the CLI writes the blob to standard output.

When you read a blob immediately after certifying it, a public aggregator can briefly return 404 before its read path catches up. Retry with backoff in that window, as the full Python example shows. See Reading blobs after upload for more.

How to check a blob's status​

Check whether a blob is available and its registered onchain information.

$ walrus blob-status --blob-id <BLOB_ID>

The CLI reports the blob's certification status and end epoch from its Sui object. See Reading blobs to learn more about certification status and Sui objects.

Full Python example​

The following script stores a blob, reads it back, and verifies the round trip against a public Testnet publisher and aggregator.

import os
import time

import requests

AGGREGATOR = "https://aggregator.walrus-testnet.walrus.space"
PUBLISHER = "https://publisher.walrus-testnet.walrus.space"


def store_blob(data: bytes, epochs: int = 5) -> str:
    response = requests.put(
        f"{PUBLISHER}/v1/blobs", params={"epochs": epochs}, data=data
    )
    response.raise_for_status()
    result = response.json()
    if "newlyCreated" in result:
        return result["newlyCreated"]["blobObject"]["blobId"]
    return result["alreadyCertified"]["blobId"]


def read_blob(blob_id: str, attempts: int = 5, backoff: float = 1.0) -> bytes:
    # A public aggregator can briefly return 404 or a 5xx right after a blob is
    # certified, before its read path catches up. Because you know the blob was
    # just stored, retry those statuses with backoff before giving up.
    response = None
    for attempt in range(attempts):
        response = requests.get(f"{AGGREGATOR}/v1/blobs/{blob_id}")
        if response.status_code == 200:
            return response.content
        retryable = response.status_code == 404 or 500 <= response.status_code < 600
        if not retryable:
            break
        time.sleep(backoff * (2**attempt))
    response.raise_for_status()
    return response.content


if __name__ == "__main__":
    original = os.urandom(1024)
    blob_id = store_blob(original)
    print(f"stored blob {blob_id}")

    downloaded = read_blob(blob_id)
    assert downloaded == original, "round trip mismatch"
    print(f"read {len(downloaded)} bytes back, round trip verified")

For more Python examples, including driving the CLI through its JSON interface and tracking Walrus events, see Using Walrus with Python.

References​

What is an upload relay?​

A Walrus Upload Relay is an alternative upload path where your client pays the relay a tip. The relay validates transactions and delegates the upload to the Walrus SDK. Your account still owns the blob and pays for its registration. Each relay serves these routes:

  • /v1/blob-upload-relay: Uploads a blob through the relay.
  • /v1/tip-config: Returns the tip configuration that the relay requires.
  • /v1/api: Serves the OpenAPI docs for the relay.

Delete a blob​

To remove a blob before its storage period ends, use the CLI delete command. It accepts multiple files, blob IDs, or object IDs, and works only for deletable blobs. Deleting a blob returns its storage resource to you.

New blobs are deletable by default. When you store through a publisher, the permanent query parameter creates a permanent blob instead, which you cannot delete.