Walrus HTTP API

Walrus HTTP API

Source constraint: All information in this skill is sourced from the Walrus HTTP API documentation. When extending this skill, only pull from these sources.

Walrus exposes a REST API through publisher (write) and aggregator (read) services. This is the simplest integration path for any language: store blobs with HTTP PUT, read them with HTTP GET. No SDK installation required.

All patterns in this skill are derived from:

• https://docs.wal.app/docs/http-api/storing-blobs
• https://docs.wal.app/docs/http-api/reading-blobs

If unsure about any endpoint, fetch the relevant page before answering.

Related skills

Skill Content

Key concepts

• Publisher. An HTTP service that accepts blob data and handles encoding, sliver distribution, and on-chain registration. You PUT data to a publisher to store it. There is no public unauthenticated publisher on Mainnet. On Mainnet, run your own authenticated publisher, use the upload relay, or use the TypeScript SDK directly. Public publisher endpoints exist only for Testnet.

• Aggregator. An HTTP service that reads blobs from Walrus storage nodes and returns them via GET requests. Aggregators are read-only and can be fronted by a CDN.

• Blob ID vs object ID. A blob ID identifies the content. A Sui object ID identifies the on-chain Blob object. You can read by either. Reading by object ID also supports HTTP header attributes.

• Consistency checks. The aggregator verifies blob integrity on read. You can enable strict checks with ?strict_consistency_check=true or skip them with ?skip_consistency_check=true if the writer is known and trusted.

Storing blobs (publisher)

Store data using HTTP PUT to the publisher:

# Store a string for 1 epoch (default)
curl -X PUT "$PUBLISHER/v1/blobs" -d "some string"

# Store a file for 5 epochs
curl -X PUT "$PUBLISHER/v1/blobs?epochs=5" --upload-file "some/file"

Query parameters

# Store as permanent for 5 epochs
curl -X PUT "$PUBLISHER/v1/blobs?epochs=5&permanent=true" --upload-file "file.dat"

# Store and send the blob object to another address
curl -X PUT "$PUBLISHER/v1/blobs?send_object_to=$ADDRESS" --upload-file "file.dat"

Store response: newly created

When a blob is stored for the first time:

{
  "newlyCreated": {
    "blobObject": {
      "id": "0xe91e...c50",
      "registeredEpoch": 34,
      "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
      "size": 17,
      "encodingType": "RS2",
      "certifiedEpoch": 34,
      "storage": {
        "id": "0x4748...5faf",
        "startEpoch": 34,
        "endEpoch": 35,
        "storageSize": 66034000
      },
      "deletable": false
    },
    "resourceOperation": {
      "registerFromScratch": {
        "encodedLength": 66034000,
        "epochsAhead": 1
      }
    },
    "cost": 132300
  }
}

Store response: already certified

When identical content already exists with sufficient lifetime:

{
  "alreadyCertified": {
    "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
    "event": {
      "txDigest": "4XQHFa9S324wTzYHF3vsBSwpUZuLpmwTHYMFv9nsttSs",
      "eventSeq": "0"
    },
    "endEpoch": 35
  }
}

The event field contains the Sui event ID you can use to find the transaction on Suiscan.

Reading blobs (aggregator)

Read blobs using HTTP GET from an aggregator:

# Read by blob ID
curl "$AGGREGATOR/v1/blobs/<BLOB_ID>" -o output.file

# Read by Sui object ID (also returns HTTP header attributes)
curl "$AGGREGATOR/v1/blobs/by-object-id/<OBJECT_ID>" -o output.file

Reading by object ID recognizes these attribute keys and returns them as HTTP headers: content-disposition, content-encoding, content-language, content-location, content-type, and link.

Publisher, aggregator, and upload relay: which to use

• Mainnet aggregator (Mysten Labs): https://aggregator.walrus-mainnet.walrus.space
• Testnet aggregator (Mysten Labs): https://aggregator.walrus-testnet.walrus.space
• Testnet publisher (Mysten Labs): https://publisher.walrus-testnet.walrus.space

The full list of public aggregators is available at docs.wal.app/operators.json (JSON) and the public services page. Public aggregators set CORS headers, so browser-based reads work directly.

Querying system info

# Get current epoch, storage cost, and network parameters
curl "$AGGREGATOR/v1/info"

Returns epoch number, epoch duration, and system parameters. Useful for calculating costs and checking the current epoch before setting epochs on a store request.

Rules

1. No public Mainnet publisher. On Mainnet, run your own authenticated publisher or use the TypeScript SDK/upload relay. Public endpoints are Testnet only.
2. New blobs are deletable by default. Explicitly set permanent=true if you need guaranteed availability.
3. Retry reads after immediate upload. CDN-fronted aggregators might briefly cache a 404 from before the blob propagated. Retry with backoff.
4. Use blob ID for content reads, object ID for attributed reads. Reading by object ID returns custom HTTP headers from blob attributes. Reading by blob ID does not.
5. Check the response type. A store response is either newlyCreated or alreadyCertified. Both are success cases.

Common mistakes

• Assuming a public publisher exists on Mainnet. It does not. You must run your own, use an upload relay, or use the TypeScript SDK directly. The upload relay at https://upload-relay.mainnet.walrus.space is the easiest mainnet write path.
• Not checking for alreadyCertified in the response. The publisher returns this when identical content already has sufficient lifetime. This is not an error.
• Reading immediately after storing and getting 404. CDN caching can cause brief 404s. Retry with backoff.
• Omitting epochs and getting 1-epoch storage. The default is 1 epoch. Always set epochs explicitly.
• Confusing publisher and aggregator roles. Publishers store (PUT). Aggregators read (GET). They are separate services with different URLs.
• Getting 413 Payload Too Large on a publisher. Some publishers limit upload size (for example, 10 MiB for public testnet publishers). For large files, use the CLI, the TypeScript SDK, or run your own publisher.
• Wondering why storageSize is ~66 MB for a tiny blob. Walrus adds ~64 MB of fixed per-blob metadata overhead regardless of blob size. For blobs smaller than ~10 MB, metadata cost dominates. Use quilts for many small blobs.
• Using old aggregator URLs. aggregator.walrus.site and aggregator.devnet.walrus.space are outdated. Use aggregator.walrus-mainnet.walrus.space for mainnet or aggregator.walrus-testnet.walrus.space for testnet.