⚠️ Current Status: Partial Implementation
This SDK is currently a partial implementation. It is designed to simulate the functionality of a real NFT marketplace SDK to allow for frontend development and prototyping.
Data-fetching actions (getTokensForCollection, getUserTokens, getNft) are functional and connected to the live Alchemy API.
Transactional actions (buyToken, listToken, createToken, etc.) are mock implementations. They log their activity to the console and simulate onProgress events but do not perform any real blockchain transactions or API calls. All data is sourced from mock files and is not live.
Introduction
The audi0 SDK provides a simple and powerful interface for building modern NFT marketplace experiences. It is designed to handle interactions with NFT data and simulate blockchain transactions, allowing you to focus on building your application’s user experience.
Client Initialization
To use the SDK, you first need to create a client instance. This is typically done in a central file, like src/lib/audi0/index.ts, and managed via the Audi0KitProvider in your application root.
code TypeScriptdownloadcontent_copyexpand_less // src/lib/audi0/index.ts
import { createClient } from ‘./audi0’;
import type { Audi0Wallet } from ‘./types’;
// Example of creating a wallet adapter (you would replace this with a real implementation)
const myWalletAdapter: Audi0Wallet = {
getAddress: async () => ‘0x0000000000000000000000000000000000000000’,
signMessage: async (message: string) => `signed:${message}`,
sendTransaction: async (tx) => `0x...txhash...`,
};
createClient({
chains: [
{
id: 1,
name: ‘mainnet’,
// In a real implementation, this would point to your live API endpoint.
baseApiUrl: ‘https://api.audi0.market/v1’,
active: true,
},
],
source: ‘audi0.market’,
wallet: myWalletAdapter, // Pass in your custom wallet adapter
});
You can then retrieve the client instance anywhere in your app using getClient().
Data Fetching Actions
These actions are connected to live on-chain data via the Alchemy SDK.
Get Tokens for a Collection
Retrieves all NFT tokens for a specific contract address. Can optionally be filtered by owner.
getTokensForCollection(contractAddress: string, network: string, options?: { limit?: number, owner?: string }): Promise<AudioNft[]>ParameterDescriptionRequiredExamplecontractAddressThe address of the NFT contract.true’0x7dc6c8e6dcc6d21d679397489785b8373b31d0ed’networkThe network to query (e.g., ‘eth-mainnet’, ‘polygon-mainnet’).true’eth-mainnet’optionsAn object for additional options.false{ owner: ‘0x123...’ }Example:
code TypeScriptdownloadcontent_copyexpand_less import { getClient } from ‘@/lib/audi0’;
const audi0Client = getClient();
const tokens = await audi0Client.getTokensForCollection(
‘0x7dc6c8e6dcc6d21d679397489785b8373b31d0ed’,
‘eth-mainnet’,
{ limit: 10 }
);
console.log(tokens);
Get User Tokens
Retrieves all NFT tokens owned by a specific user address across all collections on a given network.
getUserTokens({ userAddress: string, network: string }): Promise<AudioNft[]>ParameterDescriptionRequiredExampleuserAddressThe wallet address of the owner.true’0xbd90bfd0b71d85e279240106da1e70c72f936990’networkThe network to query.true’polygon-mainnet’Get a Single NFT
Retrieves the metadata for a single NFT by its contract address and token ID.
getNft({ contractAddress: string; tokenId: string; network: string }): Promise<AudioNft | null>ParameterDescriptionRequiredExamplecontractAddressThe address of the NFT contract.true’0xf01d323bdac88ee39543cbbc568c6fc76258ffe0’tokenIdThe ID of the token.true’1234’networkThe network to query.true’polygon-mainnet’Transactional Actions (Mock)
The SDK provides several core actions for interacting with NFTs. In the current mock implementation, these actions will log to the console and simulate progress without executing real transactions.
Creating a Token
The createToken action allows you to create a new NFT. This is different from mintToken, which creates new editions of an existing token.
createToken(params: CreateTokenParameters): Promise<CreateTokenResponse>ParameterDescriptionRequirednameThe name or title of the token.trueartistNameThe name of the primary artist.trueimageA valid URL for the token’s artwork.trueaudioUrlA valid URL for the token’s audio file.truegenreThe genre of the audio.truepriceThe initial listing price in ETH.truerecipientAddressThe wallet address that will receive the newly created token.trueExample:
code TypeScriptdownloadcontent_copyexpand_less import { getClient } from ‘@/lib/audi0’;
import type { CreateTokenParameters } from ‘@/lib/types’;
const audi0Client = getClient();
const params: CreateTokenParameters = {
name: ‘My New Song’,
artistName: ‘DJ Cadence’,
image: ‘https://placehold.co/600x600.png’,
audioUrl: ‘https://example.com/song.mp3’,
genre: ‘Electronic’,
price: 0.05,
recipientAddress: ‘0x123...’,
};
const response = await audi0Client.createToken(params);
if (response.success) {
console.log(’Token created!’, response.token);
}
Buying a Token
This action is used to buy an ERC-1155 or ERC-721 token.
buyToken(params: BuyTokenParameters): Promise<{ success: boolean }>ParameterDescriptionRequiredExampleitemsAn array of objects representing orders to be purchased.true[{ token: “0x...:1” }]walletA valid Audi0Wallet object.trueSee “Custom Wallet Adapters”.onProgressCallback to update UI state as execution progresses.true(steps) => console.log(steps)expectedPriceToken price data to protect the buyer from price moves.false{ “0x...”: { amount: 10, ... } }optionsAdditional options, such as source or skipBalanceCheck.false{ source: “audi0.market” }chainIdOverride the current active chain.false1Listing a Token
This action is used to list an ERC-1155 or ERC-721 token for sale.
listToken(params: ListTokenParameters): Promise<{ success: boolean }>ParameterDescriptionRequiredExamplelistingsAn array of listing objects.true[{ token: “0x...:1”, weiPrice: 10000... }]walletA valid Audi0Wallet object.trueonProgressCallback to update UI state as execution progresses.trueprecheckIf true, returns the steps without executing.falsefalsechainIdOverride the current active chain.false1Placing a Bid
This action is used to place a bid on an ERC-1155 or ERC-721 token.
placeBid(params: PlaceBidParameters): Promise<{ success: boolean }>ParameterDescriptionRequiredExamplebidsAn array of bid objects.true[{ weiPrice: 1000..., token: “0x...:0” }]walletA valid Audi0Wallet object.trueonProgressCallback to update UI state as execution progresses.truechainIdOverride the current active chain.false1Other Transactional Actions
The SDK includes several other mock transactional actions with similar structures:
acceptOffer(params: AcceptOfferParameters): Accepts a bid on a token.
mintToken(params: MintTokenParameters): Mints a new edition of an existing token.
cancelOrder(params: CancelOrderParameters): Cancels an active listing or bid.
transferTokens(params: TransferTokensParameters): Transfers a token to another wallet.
Please refer to src/lib/types.ts for the detailed parameter interfaces for these actions.
Custom Wallet Adapters
The audi0 SDK uses a wallet adapter pattern to normalize interactions with user wallets, allowing for custom logic when signing messages or sending transactions. This makes the SDK incredibly flexible.
To create a custom adapter, you need to implement the Audi0Wallet interface defined in src/lib/types.ts:
code TypeScriptdownloadcontent_copyexpand_less export interface Audi0Wallet {
getAddress: () => Promise<string>;
signMessage: (message: string) => Promise<string>;
sendTransaction: (tx: {
to: string;
data: string;
value?: string;
}) => Promise<string>;
}
You can then pass an instance of your custom wallet when creating the audi0 client.
Metadata Structure
The SDK is built around a robust metadata structure for audio NFTs, defined by the AudioNft interface in src/lib/types.ts. This structure supports detailed information about tracks, artwork, licensing, and more, while also conforming to OpenSea standards for compatibility. Please refer to the AudioNft type definition in src/lib/types.ts for the full schema.