0G Storage API — Opacus Docs

1. Quick Start

You only need an Opacus API key. No 0G wallet, no A0GI tokens — Opacus acts as the infra layer and pays gas on your behalf.

# 1. Get your free API key at opacus.xyz/agentboard
# 2. Upload data:
curl -X POST https://opacus.xyz/api/v1/storage/upload \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": {"task": "done", "result": 42}, "type": "json"}'
# Response: { "ok": true, "cid": "baegbe...", "size": 156 }

2. SDK Example

Install the SDK once, then store data in one line:

npm install opacus-sdk

import { OpacusClient } from 'opacus-sdk';
const client = new OpacusClient({ apiKey: process.env.OPACUS_API_KEY });

// Store any JSON object
const receipt = await client.storage.store({ data: { agent: 'alice', action: 'swap', amount: 100 } });
console.log('Stored at CID:', receipt.cid);

// Retrieve it later
const data = await client.storage.get(receipt.cid);
console.log('Retrieved:', data);

3. API Reference

POST /v1/storage/upload

Headers: Authorization: Bearer sk_...

Request Body:

{ "content": "any string or JSON object", "type": "json" }

Response:

{
  "ok": true,
  "cid": "baegbe...",
  "size": 1500
}

4. Use Cases

Archiving agent decision logs for transparency & auditability.
Storing large embeddings or model outputs during distributed processing.
Permanent, content-addressed backups of agent state.

5. Errors

413 PAYLOAD_TOO_LARGE — Max 5MB per request. Compress first for large payloads.

402 QUOTA_EXCEEDED — Daily free quota reached. See pricing page for upgrade options.

6. Best Practices

Compress JSON before upload (gzip saves ~60–70% on typical agent logs).
Always save the returned cid — it's the only way to retrieve your data.
For agent audit trails, store structured objects with a ts timestamp field.

POST /v1/storage/upload

Headers: Authorization: Bearer sk_...

Request Body: Form-Data or JSON.

{ "content": "{"task":"done"}", "type": "json" }

Response Schema:

{
  "ok": true,
  "cid": "baegbe...",
  "size": 1500
}

5. Examples

TypeScript SDK:

const receipt = await opacus.ogStorage.store({ data: myData });
console.log('Saved to 0G at CID:', receipt.cid);

6. Errors

413 PAYLOAD_TOO_LARGE - Max 5MB per direct request.

7. Best Practices

Compress data aggressively before upload. Retain the CID to fetch egress context.