This package has been deprecated

Author message:

This client is for the old API, sunset on Jan 9 2024. Use the new client and API instead: @web3-storage/w3up-client.
TypeScript icon, indicating that this package has built-in type declarations

4.5.5 • Public • Published

The JavaScript API client for

Getting started

Install the package using npm

npm install


The code below shows how you create a new api client, and use it to put your files to web3, and get them back again.

Sign in to, create an API token, and use it in place of API_TOKEN when creating your instance of the client.

import { Web3Storage } from ''

// Construct with token and endpoint
const client = new Web3Storage({ token: API_TOKEN })

const fileInput = document.querySelector('input[type="file"]')

// Pack files into a CAR and send to
const rootCid = await client.put(fileInput.files) // Promise<CIDString>

// Get info on the Filecoin deals that the CID is stored in
const info = await client.status(rootCid) // Promise<Status | undefined>

// Fetch and verify files from
const res = await client.get(rootCid) // Promise<Web3Response | null>
const files = await res.files() // Promise<Web3File[]>

for (const file of files) {
  console.log(`${file.cid} ${} ${file.size}`)


Management of mutable name records with IPNS has now moved to the w3name client.


Run npm test to test the ESM code, CJS, and in the browser via playwright-test. 100% test coverage is required by the hundreds module.

To test in individual environments, you'll need two terminal windows open. In the first, start up the mock API by running npm run mock:api. In the second, you can then run npm run test:web, npm run test:esm or npm run test:cjs.

Tests are written in mocha and use a mock API server to assert functionality. When adding a new method to the client, add a test/<method>.spec.js test suite to go with it.

The mock api is built with smoke file-based mock server. You add a files to the test/mocks/api directory, and the file name determines which API enpoint you are mocking. You can provide a .json for a static response, or a .js file to add some logic to the mock.

  • post_car.js handles POST /car requests.
  • get_car#@cid.js handes GET /car/:cid requests. The cid part of the path is provided to the mock as params.cid.

Add more mocks as required.




Package Sidebar


npm i

Weekly Downloads





(Apache-2.0 OR MIT)

Unpacked Size

1.21 MB

Total Files


Last publish


  • alanshaw
  • ipfsbot
  • it-dag-house
  • olizilla
  • vascosantos