Web3 Ipfs
Description
Experience seamless file management on our IPFS host with our SDK. Utilize API keys to effortlessly pin, unpin, retrieve, and securely access files through the gateway, ensuring efficient and secure file operations. Simplify decentralized file management with ease and confidence.
Installation
npm install aioz-w3ipfs-sdk
Setup
To start, simply require the W3IPFS SDK and set up an instance with your W3IPFS API Keys or your JWT key. Don't know what your keys are? Check out your Account Page.
In the example below we provided with 2 ways to call the W3IPFS SDK.
import W3IpfsClient from 'aioz-w3ipfs-sdk'
const client = new W3IpfsClient('key', 'secret-key')
import W3IpfsClient from 'aioz-w3ipfs-sdk'
const client = new W3IpfsClient({ pinningApiKey: 'key', pinningSecretApiKey: 'secret-key' })
Quickly test that you can connect to the API with the following call:
client
.testAuthentication()
.then((result) => {
console.log(result)
})
.catch((err) => {
console.log(err)
})
Usage
Once you've set up your instance, using the W3IPFS SDK is easy. Simply call your desired function and handle the results of the promise.
pinByHash
The request body when pin a file by CID will look like this:
{
hash_to_pin: CID,
metadata: {
name: string,
keyvalues: {
key1: value1,
key2: value2
}
}
}
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": false,
"is_pin_by_hash": true,
"is_dir": false,
"metadata": {
"name": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
client
.pinByHash({
hashToPin: 'bafyb...2goq',
options: {
metadata: {
name: 'bafyb...2goq',
keyvalues: {
description1: 'this is description1',
description2: 'this is description2',
},
},
},
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
pinFilesToIPFS
This API allows you to pin a files to IPFS using the provided pinning API key and secret key.
Example metadata:
{"name": "sample name", "keyvalues":{"key1": "value1","key2": "value2"}}
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": false,
"is_pin_by_hash": false,
"sub_hash_status": "string",
"is_dir": false,
"metadata": {
"name": "string",
"type": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
import NodeFormData from 'form-data'
import * as fs from 'fs'
import path from 'path'
const filePath = path.join(__dirname, '../assets/file.txt')
const metadataPath = path.join(__dirname, '../assets/sample.json')
const readableStreamForFile = fs.createReadStream(filePath)
const readableStreamForFile2 = fs.createReadStream(metadataPath)
export const w3IpfsOptions: PinOptions = {}
client
.pinFilesToIPFS({
files: [readableStreamForFile2, readableStreamForFile],
options: {
metadata: {
name: 'folder abc',
keyvalues: {
description: 'This is a folder abc',
},
},
},
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
pinFolderToIPFS
This API allows you to pin a folder to IPFS using the provided pinning API key and secret key.
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": false,
"is_pin_by_hash": false,
"sub_hash_status": "string",
"is_dir": true,
"metadata": {
"name": "string",
"type": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
import path from 'path'
const folderPath = path.join(__dirname, '../assets/')
client
.pinFolderToIPFS({
recursive: 0,
sourcePath: folderPath,
options: {
metadata: {
name: 'folder',
keyvalues: {
description: 'This is a folder',
},
},
},
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
unpin
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"size": number,
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"is_pin_by_hash": true,
"is_dir": false,
"metadata": {
"name": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
client
.unpin('file-id')
.then((result) => {
console.log(result)
})
.catch((err) => {
console.log(err)
})
pinNft
The metadata JSON file will look like this:
{
"name": "My Awesome NFT",
"description": "This is an NFT that represents my creativity as a digital artist!",
"properties": [
{
"trait_type": "Color",
"value": "Red"
},
{
"trait_type": "Rarity",
"value": "Medium"
}
]
}
Response
{
"data": {
"id": "string",
"asset_cid": "string",
"metadata_cid": "string",
"asset_pin_id": "string",
"metadata_pin_id": "string",
"size": number,
"user_id": "string",
"created_at": "2023-01-01T11:11:11.111111Z",
"updated_at": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"metadata_asset": {
"name": "string",
"type": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
import * as fs from 'fs'
import path from 'path'
const imagePath = path.join(__dirname, './file.txt')
const metadataPath = path.join(__dirname, './sample.json')
const readableStreamForFile = fs.createReadStream(imagePath)
const readableStreamMetadataFile = fs.createReadStream(metadataPath)
client.pinNft({
fileStream: readableStreamForFile,
metadata: {
name: 'test',
description: 'test',
properties: [
{
trait_type: 'Color',
value: 'Red',
},
{
trait_type: 'Size',
value: 'M',
},
],
},
})
client
.pinNftByStreamMetadata({
fileStream: readableStreamForFile,
metadataStream: readableStreamMetadataFile,
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
pinNftByHash
The metadata JSON file will look like this:
{
"name": "My Awesome NFT",
"description": "This is an NFT that represents my creativity as a digital artist!",
"properties": [
{
"trait_type": "Color",
"value": "Red"
},
{
"trait_type": "Rarity",
"value": "Medium"
}
]
}
Response
{
"data": {
"id": "string",
"asset_cid": "string",
"metadata_cid": "string",
"asset_pin_id": "string",
"metadata_pin_id": "string",
"size": number,
"user_id": "string",
"created_at": "2023-01-01T11:11:11.111111Z",
"updated_at": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"metadata_asset": {
"name": "string",
"type": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
import * as fs from 'fs'
import path from 'path'
const metadataPath = path.join(__dirname, './sample.json')
const readableStreamMetadataFile = fs.createReadStream(metadataPath)
client
.pinNftByHash({
hashToPin: 'bafkr...w7m',
metadata: {
name: 'My Awesome NFT',
description: 'This is an NFT that represents my creativity as a digital artist!',
properties: [
{
trait_type: 'Color',
value: 'Red',
},
{
trait_type: 'Rarity',
value: 'Medium',
},
],
},
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
client
.pinNftByHashAndMetadataStream({
hashToPin: 'bafk...f73u',
metadataStream: readableStreamMetadataFile,
})
.then((res) => console.log({ res }))
.catch((err) => console.log({ err }))
unpinNft
Example Code
client
.unpinNft('nft-id')
.then((result) => {
console.log(result)
})
.catch((err) => {
console.log(err)
})
testAuthentication
Response
{
"message": "Congratulations! You are communicating with the Web3 IPFS API!"
}
Example Code
client
.testAuthentication()
.then((result) => {
console.log(result)
})
.catch((err) => {
console.log(err)
})
getPinList
Response
{
"data": {
"totals": {
"files": number,
"size": number
},
"pins": [
{
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"size": number,
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"is_pin_by_hash": true,
"sub_hash_status": "string",
"is_dir": false,
"metadata": {
"name": "string"
},
"status": "string"
}
]
},
"status": "success"
}
Example Code
client
.getPinList({
offset: 0,
limit: 10,
pinned: 'true',
sortBy: 'size',
sortOrder: 'DESC',
metadata: {
keyvalues: {
bbbn: '',
},
},
})
.then((result: PinListResponse) => {
console.log({ result: result.data })
})
.catch((error) => {
console.log(error)
})
getPinByID
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"size": number,
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"is_pin_by_hash": true,
"sub_hash_status": "string",
"is_dir": false,
"metadata": {
"name": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
client
.getPinByID('pin id')
.then((result) => {
console.log({ result })
})
.catch((error) => {
console.log(error)
})
getPinByCID
Response
{
"data": {
"id": "string",
"file_record_id": "string",
"root_hash": "string",
"cid": "string",
"size": number,
"user_id": "string",
"date_pinned": "2023-01-01T11:11:11.111111Z",
"date_unpinned": "2023-11-11T11:11:11.111111Z",
"pinned": true,
"is_pin_by_hash": true,
"sub_hash_status": "string",
"is_dir": false,
"metadata": {
"name": "string"
},
"status": "string"
},
"status": "success"
}
Example Code
client
.getPinByCID('bafy...')
.then((result) => {
console.log(result)
})
.catch((err) => {
console.log(err)
})