CAR Import (DAG Import)

Importe DAGs IPFS inteiros em uma única requisição usando arquivos CAR (Content Addressable aRchive). Seus CIDs são preservados exatamente — sem re-chunking ou re-hashing.

O que é um arquivo CAR?

Um arquivo CAR empacota uma árvore de diretórios IPFS inteira ou um DAG em um único arquivo portátil. Cada bloco é armazenado com seu CID original, então o serviço importa tudo como está. Isso significa:

• Preservação de CID — calcule os CIDs localmente, verifique se o serviço retorna exatamente o mesmo CID
• Upload em lote — envie centenas de arquivos em uma única requisição em vez de um por um
• Migração de provedor — exporte um DAG de outro provedor, importe para o IPFS Ninja com CIDs idênticos
• DAGs personalizados — envie qualquer estrutura de dados IPLD diretamente

REST API

POST /upload/new

Mesmo endpoint que uploads regulares — adicione car: true para sinalizar uma importação CAR.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
content	string	Sim	Arquivo CAR codificado em Base64
car	boolean	Sim	Defina como true para habilitar a importação CAR
description	string	Não	Breve descrição da importação
folderId	string	Não	ID da pasta para organizar o conteúdo importado
metadata	object	Não	Pares chave-valor personalizados (mesmas regras dos uploads regulares)

Exemplo: Importar um arquivo CAR com curl

Passo 1: Crie um arquivo CAR a partir de um diretório local usando ipfs-car:

npx ipfs-car pack ./my-directory -o my-archive.car

Passo 2: Envie o arquivo CAR:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"$(base64 -w0 my-archive.car)\",
    \"car\": true,
    \"description\": \"My directory import\"
  }"

Exemplo: Importar um arquivo CAR com JavaScript

import fs from "fs";

const carBuffer = fs.readFileSync("my-archive.car");
const base64Content = carBuffer.toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: base64Content,
    car: true,
    description: "My directory import"
  })
});

const result = await response.json();
console.log("Root CID:", result.cid);
console.log("Gateway:", result.uris.url);

Exemplo: Importar um arquivo CAR com Python

import requests
import base64

with open("my-archive.car", "rb") as f:
    car_content = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.ipfs.ninja/upload/new",
    headers={
        "X-Api-Key": "bws_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "content": car_content,
        "car": True,
        "description": "My directory import"
    }
)

result = response.json()
print("Root CID:", result["cid"])
print("Gateway:", result["uris"]["url"])

Resposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 4.2,
  "car": true,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

S3-Compatible API

Use o cabeçalho x-amz-meta-import: car em uma requisição PutObject para importar um arquivo CAR pela API S3.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-archive.car",
  Body: fs.readFileSync("my-archive.car"),
  ContentType: "application/vnd.ipld.car",
  Metadata: { import: "car" }   // ← aciona a importação CAR
}));

console.log("Root CID:", result.ETag);

MCP Server

A ferramenta ipfs_import_car está disponível no MCP Server (v1.3.0+):

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

Criando Arquivos CAR

A partir de um diretório (recomendado)

Use a ferramenta CLI ipfs-car:

# Install
npm install -g ipfs-car

# Pack a directory into a CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Check the root CID before uploading
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

A partir de um nó IPFS em execução

Exporte qualquer CID como arquivo CAR usando o CLI do Kubo:

ipfs dag export QmXyz... > my-archive.car

Programaticamente com JavaScript

Use a biblioteca @ipld/car:

import { CarWriter } from "@ipld/car";
import { CID } from "multiformats/cid";
import * as raw from "multiformats/codecs/raw";
import { sha256 } from "multiformats/hashes/sha2";

// Create blocks
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Write CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Collect output
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Verificando a Integridade do CID

O principal benefício da importação CAR é a preservação do CID. Você pode verificar se o CID raiz é o mesmo antes e depois do upload:

# 1. Pack directory and note the root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Upload to IPFS Ninja
curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 collection.car)\", \"car\": true}" \
  | jq .cid
# "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
# ✓ CIDs match — content imported exactly as built locally

Migrando de Outro Provedor

Do Pinata

# Export from Pinata using IPFS gateway
ipfs dag export QmYourCID > export.car

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Do Filebase

# Filebase supports CAR export via their S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Limites

Limite	Valor
Tamanho máximo do arquivo CAR	100 MB
Raiz única máxima	Deve ter pelo menos um CID raiz
Formato CAR	CARv1 (universalmente suportado)
Disponibilidade	Todos os planos (Dharma, Bodhi, Nirvana)

Os limites de armazenamento e contagem de arquivos do seu plano se aplicam. O DAG importado conta como uma entrada de arquivo, e o tamanho do arquivo CAR é deduzido da sua cota de armazenamento.

Solução de Problemas

"invalid CAR file: too small"

O conteúdo enviado tem menos de 40 bytes, o que é pequeno demais para ser um arquivo CAR válido. Certifique-se de que está enviando o conteúdo CAR completo codificado em Base64.

"File too large. Maximum upload size is 100 MB."

O arquivo CAR decodificado excede 100 MB. Divida seu conteúdo em vários arquivos CAR menores usando o pacote carbites, ou envie os arquivos individualmente.

"dag/import did not return a root CID"

O nó IPFS não conseguiu processar o arquivo CAR. Verifique se o arquivo é um arquivo CARv1 válido:

ipfs-car roots my-archive.car

Se este comando falhar, o arquivo CAR está malformado. Regenere-o com ipfs-car pack ou ipfs dag export.

"not enough storage"

O limite de armazenamento do seu plano foi atingido. Exclua arquivos não utilizados ou faça upgrade do seu plano em ipfs.ninja/pricing.