IPFS endpoints

Upload and retrieve SPECTER meta-address payloads through configured Pinata gateway

Upload meta-address

POST /api/v1/ipfs/upload validates meta-address hex and uploads bytes through Pinata v3.

Retrieve raw bytes

GET /api/v1/ipfs/:cid returns application/octet-stream from backend proxy.

Endpoints

• POST /api/v1/ipfs/upload
• GET /api/v1/ipfs/:cid

Upload request schema

meta_address · string · required

Hex-encoded SPECTER meta-address.

name · string

Optional display/pin name sent to Pinata upload API.

Upload response schema

cid · string · required

Uploaded IPFS content identifier.

text_record · string · required

Formatted value for name service storage, e.g. ipfs://<cid>.

Retrieve request params

cid · string · required

CID to retrieve through backend gateway client.

Typical flow

1. Upload meta-address bytes

   Call POST /api/v1/ipfs/upload and capture the returned CID.

2. Set name-service record

   Write text_record into ENS specter text record or SuiNS content hash.

3. Verify retrieval

   Call GET /api/v1/ipfs/:cid and confirm raw bytes are returned.

Example calls

Upload (cURL)

curl -s -X POST http://localhost:3001/api/v1/ipfs/upload \
  -H "Content-Type: application/json" \
  -d '{"meta_address":"<HEX_META_ADDRESS>","name":"alice.eth-specter"}' | jq .

Retrieve (cURL)

curl -s "http://localhost:3001/api/v1/ipfs/<CID>" --output meta-address.bin

JavaScript

const up = await fetch("http://localhost:3001/api/v1/ipfs/upload", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ meta_address, name: "alice.eth-specter" })
});

const uploaded = await up.json();
console.log(uploaded.cid, uploaded.text_record);

Required environment variables

Upload requires PINATA_JWT. Retrieval requires PINATA_GATEWAY_URL and PINATA_GATEWAY_TOKEN.

Gateway and caching behavior

Downloads use configured dedicated gateway and can be cached in-memory by CID when cache is enabled.

Response content type for GET

GET /api/v1/ipfs/:cid responds with raw bytes and Content-Type: application/octet-stream.