IPFS SDK for Go

A Go SDK for interacting with IPFS HTTP gateway services. Provides a clean, idiomatic interface for common IPFS operations including pinning, DNS management, IPNS, website deployment, and file uploads.

Features

• Pinning Service - Pin and unpin content using generated client from IPFS Pinning Service API spec
• DNS Service - Manage DNS zones and records with DNSLink support
• IPNS Service - Inter-Planetary Naming System key management
• Websites Service - Deploy and manage gateway websites
• Upload Service - TUS resumable uploads and HTTP POST with memory-efficient CAR generation
• OpenAPI-driven - Code generated from swagger.yaml for type safety
• Configurable retry - Exponential backoff with customizable attempts

Installation

go get go.lumeweb.com/ipfs-sdk

Quick Start

import (
"context""log""go.lumeweb.com/ipfs-sdk"
)
funcmain() {
client, err:=ipfs.NewClient("https://api.example.com", "your-bearer-token")
iferr!=nil {
log.Fatal(err)
}
ctx:=context.Background()
// List all pinspins, err:=client.Pinning().ListPins(ctx)
iferr!=nil {
log.Fatal(err)
}
log.Printf("Found %d pins", len(pins))
}

Services

Pinning Service

// List, add, get status, and remove pinspins, _:=client.Pinning().ListPins(ctx)
c, _:=cid.Decode("QmYourCidHere")
pin, _:=client.Pinning().AddPin(ctx, c)
status, _:=client.Pinning().GetPin(ctx, pin.GetRequestId())
client.Pinning().RemovePin(ctx, pin.GetRequestId())

DNS Service

// Manage DNS zones and DNSLink recordszones, _:=client.DNS().ListZones(ctx)
zone, _:=client.DNS().CreateZone(ctx, "example.com", nameservers)
record, _:=client.DNS().CreateRecord(ctx, zone.Id, request)
records, _:=client.DNS().ListRecords(ctx, zone.Id)

IPNS Service

// List, create, publish, and resolve IPNS keyskeys, _:=client.IPNS().ListKeys(ctx)
key, _:=client.IPNS().CreateKey(ctx, "my-key")
publishResult, _:=client.IPNS().Publish(ctx, key.Id, cid)
resolveResult, _:=client.IPNS().Resolve(ctx, name)

Websites Service

// Deploy and manage gateway websiteswebsites, _:=client.Websites().List(ctx)
site, _:=client.Websites().Create(ctx, "domain.com", cid, "ipfs")
updatedSite, _:=client.Websites().Update(ctx, site.Id, domain, cid, protocol)

Upload Service

// Upload from filesystem (CAR generation with automatic TUS/POST selection)filesystem:=os.DirFS("path/to/directory")
result, _:=client.Upload().UploadFromFS(ctx, filesystem, "directory-name", &ipfs.UploadOptions{
MemoryLimit: 100*1024*1024,
})
// Upload a single file (convenience method - wraps file in filesystem)file, _:=os.Open("path/to/file.txt")
deferfile.Close()
result, _:=client.Upload().UploadFile(ctx, file, "file.txt", &ipfs.UploadOptions{
MemoryLimit: 100*1024*1024,
})
// Upload raw data stream (no CAR generation)reader:=strings.NewReader("your data")
size:=int64(len("your data"))
result, _:=client.Upload().Upload(ctx, reader, "stream.txt", size)
// result.CID contains the uploaded content CID

Configuration

import (
"time"
httputil "go.lumeweb.com/ipfs-sdk/internal/http"
)
retryConfig:= httputil.RetryConfig{
Attempts: 5,
MaxJitter: 10*time.Second,
MaxDelay: 60*time.Second,
}
client, _:=ipfs.NewClient(
"https://api.example.com",
"your-token",
ipfs.WithRetryConfig(retryConfig),
)

Host Override

For testing with vhost configurations, you can override the Host header while connecting to a specific IP address:

client, _:=ipfs.NewClient(
"https://api.example.com",
"your-token",
ipfs.WithHostOverride("api.example.com", "127.0.0.1:8080"),
)

This is useful for:

• Testing locally against remote API contracts
• Developing with vhost-based routing
• Integration testing with custom domains

Note: Host override now applies to all services including PinningService.

Retry Behavior

Default retry configuration:

• 3 attempts with exponential backoff
• Unrecoverable codes (not retried): 400, 401, 403, 404, 405, 409, 422
• Rate limit (429) always retried

Architecture

The SDK uses a layered architecture:

Client Entry Point (Pinning, DNS, IPNS, Websites, Upload)
↓
Service Interfaces (Type-safe adapters)
↓
Generated OpenAPI Clients
├── Main API (swagger.yaml → oapi-codegen)
└── Pinning Service (ipfs-pinning-service.yaml → oapi-codegen)
↓
HTTP Infrastructure (Retry, Auth, net/http)

The PinningService is generated from the official IPFS Pinning Service API spec for full compliance and maximum flexibility.

Upload Package

Implements two-pass CAR generation for memory-efficient large file handling:

1. Pass 1: Build summary with metadata (CIDs, sizes, tree structure)
2. Pass 2: Generate CARv1 on demand using LRU blockstore (default 100MB limit)
3. Enables processing of content larger than available RAM

Development

# Build
go build -v ./...
# Test with coverage
go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -func=coverage.out
# Generate code
go generate ./internal/client
go generate ./internal/pinning
mockery
# Dependencies
go mod download
go mod tidy

Contributing

See AGENTS.md for development guidelines and project architecture details.

License

MIT License – see LICENSE for details.

Copyright (c) 2026 Hammer Technologies LLC