Skip to main content

Overview

The IPFS contract provides methods to upload images and token metadata to IPFS (InterPlanetary File System). These are typically used when creating new tokens or auctions.

Upload Image

Upload an image file to IPFS and receive the IPFS hash.
// Browser environment
const file = document.querySelector('input[type="file"]').files[0];

const response = await client.ipfs.uploadImage({
  body: {
    image: file,
  },
});

if (response.status === 200) {
  const ipfsHash = response.body.result;
  console.log('Image uploaded:', `ipfs://${ipfsHash}`);
}

Node.js Environment

import fs from 'fs';
import { FormData, File } from 'formdata-node';

const fileBuffer = fs.readFileSync('./token-image.png');
const file = new File([fileBuffer], 'token-image.png', { type: 'image/png' });

const response = await client.ipfs.uploadImage({
  body: {
    image: file,
  },
});

if (response.status === 200) {
  console.log('IPFS Hash:', response.body.result);
}

Response

Returns the IPFS hash as a string (e.g., QmX...).

Upload Metadata

Upload token metadata to IPFS, including name, description, image reference, and vesting configuration.
const response = await client.ipfs.uploadMetadata({
  body: {
    name: 'My Token',
    description: 'A revolutionary new token',
    image_hash: 'QmX...', // IPFS hash from uploadImage
    social_links: [
      {
        label: 'Website',
        url: 'https://mytoken.xyz',
      },
      {
        label: 'Twitter',
        url: 'https://twitter.com/mytoken',
      },
    ],
    vesting_recipients: [
      {
        address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
        percentage: 100,
      },
    ],
    fee_receiver: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  },
});

if (response.status === 200) {
  const metadataHash = response.body.result;
  console.log('Metadata uploaded:', `ipfs://${metadataHash}`);
}

Parameters

  • name (required): Token name
  • description (required): Token description
  • image_hash (required): IPFS hash of the token image
  • social_links (required): Array of social link objects
    • label: Link label (e.g., “Website”, “Twitter”)
    • url: Full URL
  • vesting_recipients (required): Array of vesting recipient objects
    • address: Recipient address
    • percentage: Percentage allocation (must total 100)
  • fee_receiver (required): Address to receive trading fees

Response

Returns the IPFS metadata hash as a string.

Complete Workflow

Upload image, then metadata, then create auction:
// 1. Upload image
const imageResponse = await client.ipfs.uploadImage({
  body: { image: imageFile },
});

if (imageResponse.status !== 200) {
  throw new Error('Image upload failed');
}

const imageHash = imageResponse.body.result;

// 2. Upload metadata
const metadataResponse = await client.ipfs.uploadMetadata({
  body: {
    name: 'My Token',
    description: 'Token description',
    image_hash: imageHash,
    social_links: [
      { label: 'Website', url: 'https://example.com' },
    ],
    vesting_recipients: [
      { address: '0x...', percentage: 100 },
    ],
    fee_receiver: '0x...',
  },
});

if (metadataResponse.status !== 200) {
  throw new Error('Metadata upload failed');
}

const metadataHash = metadataResponse.body.result;

// 3. Create auction with metadata URI
const auctionResponse = await client.auctions.createDynamicAuction({
  body: {
    template_id: 'template-uuid',
    metadata: {
      token_name: 'My Token',
      token_symbol: 'MTK',
      token_uri: `ipfs://${metadataHash}`,
      user_address: '0x...'
    },
  },
  query: {
    chainId: 8453, // Base Mainnet
  }
});

if (auctionResponse.status === 200) {
  console.log('Auction created successfully!');
}

Examples

Multiple Vesting Recipients

const response = await client.ipfs.uploadMetadata({
  body: {
    name: 'Community Token',
    description: 'Token for community',
    image_hash: 'QmX...',
    social_links: [
      { label: 'Discord', url: 'https://discord.gg/...' },
    ],
    vesting_recipients: [
      { address: '0x1111111111111111111111111111111111111111', percentage: 60 },
      { address: '0x2222222222222222222222222222222222222222', percentage: 30 },
      { address: '0x3333333333333333333333333333333333333333', percentage: 10 },
    ],
    fee_receiver: '0x...',
  },
});

Validate Percentages

const recipients = [
  { address: '0x...', percentage: 60 },
  { address: '0x...', percentage: 40 },
];

const totalPercentage = recipients.reduce((sum, r) => sum + r.percentage, 0);

if (totalPercentage !== 100) {
  throw new Error(`Percentages must total 100, got ${totalPercentage}`);
}

const response = await client.ipfs.uploadMetadata({
  body: {
    // ... other fields
    vesting_recipients: recipients,
  },
});
Vesting recipient percentages must total exactly 100. The API will reject invalid configurations.

Supported Image Formats

Common image formats are supported:
  • PNG
  • JPG/JPEG
  • GIF
  • SVG
  • WebP
For best results, use square images (1:1 aspect ratio) with at least 512x512 resolution.