Skip to main content

Gateway Developer Guide

This guide provides technical details for integrating the Net Gateway into your applications.

URL Structure​

The gateway uses a standardized URL format:

/net/{chainId}/storage/{mode}/{operator}/{key}/{version}

Path Parameters​

ParameterRequiredDescriptionExample
chainIdYesChain ID number8453 (Base), 1 (Ethereum)
modeYesAccess mode: load or rawload, raw
operatorYesAddress that stored the data0x17EeF8C6F9edCBceb3dEE33eF277A1F33C504629
keyYesStorage key (URL-encoded if needed)gm, mona%20lisa
versionNoHistorical version index (0 = first version)0, 1, 2

Access Modes​

Load Mode (/load): Returns processed data with XML embeds resolved. The gateway detects the content type and returns data with the appropriate Content-Type header (e.g., text/html, application/json, image/png). Use this for serving content directly to users or applications.

Raw Mode (/raw): Returns unprocessed data as JSON with three fields: key (bytes32 hex), text (description/filename), and data (raw content). XML embeds are not resolved. Use this when you need the complete raw storage record or want to handle XML resolution yourself.

Component Details​

Chain ID: Specifies which blockchain network to query (e.g., 8453 for Base, 1 for Ethereum Mainnet).

Mode: Determines how data is processed and returned - load for processed content or raw for unprocessed JSON.

Operator: The Ethereum address that stored the data. Multiple users can store data with the same key - the operator address ensures you get the right data.

Key: The storage key identifier. String keys are automatically hashed to bytes32 onchain.

Version: Optional. Specifies which historical version to retrieve (0 = first version, 1 = second version, etc.). If omitted, returns the latest version.

Examples​

Latest Version - Load Mode​

GET https://storedon.net/net/8453/storage/load/0x17EeF8C6F9edCBceb3dEE33eF277A1F33C504629/gm

Returns the most recent processed version of the gm key with detected Content-Type.

Latest Version - Raw Mode​

GET https://storedon.net/net/8453/storage/raw/0x17EeF8C6F9edCBceb3dEE33eF277A1F33C504629/gm

Returns the latest raw version as JSON:

{
  "key": "0x676d000000000000000000000000000000000000000000000000000000000000",
  "text": "greeting.txt",
  "data": "Hello, world!"
}

Historical Version​

GET https://storedon.net/net/8453/storage/load/0x17EeF8C6F9edCBceb3dEE33eF277A1F33C504629/gm/0

Returns the first version (version 0) of the processed data.

GET https://storedon.net/net/8453/storage/raw/0x17EeF8C6F9edCBceb3dEE33eF277A1F33C504629/gm/0

Returns the first version (version 0) as raw JSON.

URL-Encoded Keys​

GET https://storedon.net/net/8453/storage/load/0x7a9f83c02765f0072d6adc54bb3ab3293d241c33/mona%20lisa

The key mona lisa is URL-encoded as mona%20lisa.

Different Chains​

# Base
https://storedon.net/net/8453/storage/load/0x.../key

# Ethereum Mainnet
https://storedon.net/net/1/storage/load/0x.../key

# Base Sepolia
https://storedon.net/net/84532/storage/load/0x.../key

Response Format​

Success Response - Load Mode​

Load mode returns processed data with automatic Content-Type detection:

  • Text/HTML: Detected automatically, returned as text/html
  • JSON: Detected automatically, returned as application/json
  • Images: Detected by content, returned with appropriate image MIME type
  • Other: Defaults to text/plain

The response body contains the processed data directly. XML embeds are resolved recursively.

Response Headers:

  • Content-Type: Detected MIME type based on content

Success Response - Raw Mode​

Raw mode returns a JSON object with the complete raw storage record:

{
  "key": "0x676d000000000000000000000000000000000000000000000000000000000000",
  "text": "greeting.txt",
  "data": "Hello, world!"
}

Fields:

  • key: Storage key as bytes32 hex (e.g., 0x676d00...)
  • text: Description or filename (may be empty string)
  • data: Raw content as string (hex converted to UTF-8, no XML resolution)

Response Headers:

  • Content-Type: application/json

Error Responses​

Standard HTTP status codes:

  • 400 Bad Request: Invalid parameters (chainId, operator, key, version)
  • 404 Not Found: Data doesn't exist for the given key-operator pair
  • 413 Payload Too Large: Response exceeds 20 MB limit
  • 500 Internal Server Error: Gateway error

All errors return JSON:

{
  "error": "Error message",
  "details": "Additional details (if available)"
}

Use Cases​

Content Addressing​

Use Net Gateway URLs as permanent content addresses, similar to IPFS:

<img src="https://storedon.net/net/8453/storage/load/0x.../profile-image" />

API Integration​

Integrate Net Storage into your applications:

// Load processed data
const response = await fetch(
  "https://storedon.net/net/8453/storage/load/0x.../config"
);
const config = await response.json();

// Or get raw storage record
const rawResponse = await fetch(
  "https://storedon.net/net/8453/storage/raw/0x.../config"
);
const { key, text, data } = await rawResponse.json();

Cross-App Data Sharing​

Access storage data from any application:

// Read user profile stored by another app (processed)
const profile = await fetch(
  "https://storedon.net/net/8453/storage/load/0xUserAddress/profile"
);

// Or get raw profile data
const rawProfile = await fetch(
  "https://storedon.net/net/8453/storage/raw/0xUserAddress/profile"
);
const { key, text, data } = await rawProfile.json();

Version History​

Access historical versions of stored data:

// Get first version (processed)
const v0 = await fetch(
  "https://storedon.net/net/8453/storage/load/0x.../key/0"
);

// Get latest version (processed)
const latest = await fetch(
  "https://storedon.net/net/8453/storage/load/0x.../key"
);

// Get raw version with complete storage record
const rawV0 = await fetch(
  "https://storedon.net/net/8453/storage/raw/0x.../key/0"
);
const { key, text, data } = await rawV0.json();