@inscrib3/sdk NPM

@inscrib3/sdk

A TypeScript SDK for interacting with the Inscrib3 API, providing a simple interface for managing Ordinals drops on Bitcoin.

Installation

npm install @inscrib3/sdk

Quick Start

import sdk from '@inscrib3/sdk';

// Initialize with default API endpoint (https://api.inscrib3.com)
const inscrib3 = sdk();

// Initialize with custom Network and Chain (Bitcoin and Fractal are supported)
const inscrib3 = sdk('signet', 'bitcoin');

// Create a new drop
const createDrop = async () => {
  const result = await inscrib3.drops.create(
    'My Ordinals Collection',  // name
    'ORD',                    // symbol
    'A unique collection',    // description
    iconFile,                 // File object
    '10000',                  // price in sats
    recipientAddress,         // recipient's address
    recipientPublicKey,       // recipient's public key
    userAddress,              // creator's address
    authMessage,              // auth message
    authSignature             // auth signature
  );
  
  console.log('Created drop with ID:', result.id);
};

API Reference

Initialization

The SDK is initialized with an optional API endpoint:

const inscrib3 = sdk(apiEndpoint?: string);

If no endpoint is provided, it defaults to https://api.inscrib3.com.

Authentication

All API calls require authentication using three components:

address: Your wallet address
message: Authentication message
signature: Signed authentication message

These are passed as parameters to each method and are used to create a Basic Auth header.

Drops Management

Create a Drop

Creates a new Ordinals drop.

const result = await inscrib3.drops.create(
  name: string,
  symbol: string,
  description: string,
  icon: File,
  price: string,
  recipientAddress: string,
  recipientPublicKey: string,
  address: string,
  message: string,
  signature: string
);

Parameters:

name: Name of the drop
symbol: Symbol for the drop
description: Description of the drop
icon: File object for the drop's icon
price: Price in sats
recipientAddress: Address to receive payments
recipientPublicKey: Public key for the recipient address
address: Creator's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { id: string }

Get All Drops

Retrieves all drops for the authenticated user.

const drops = await inscrib3.drops.all(
  address: string,
  message: string,
  signature: string
);

Parameters:

address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: Array of drop objects:

{
  id: string,
  name: string,
  symbol: string,
  description: string,
  icon: string,
  price: string,
  recipientAddress: string,
  recipientPublicKey: string,
  supply: string,
  minting: string,
  minted: string
}[]

Get Drop Details

Retrieves details for a specific drop.

const drop = await inscrib3.drops.read(
  id: string,
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop to retrieve
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: Drop object:

{
  name: string,
  symbol: string,
  description: string,
  icon: string,
  price: string,
  recipientAddress: string,
  recipientPublicKey: string,
  supply: string,
  minting: string,
  minted: string
}

Remove a Drop

Removes a drop.

const result = await inscrib3.drops.remove(
  id: string,
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop to remove
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { id: string }

Mint from a Drop

Initiates the minting process for a drop.

const result = await inscrib3.drops.mint(
  id: string,
  paymentAddress: string,
  paymentPublicKey: string,
  recipientAddress: string,
  recipientPublicKey: string,
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop to mint from
paymentAddress: Address to make payment from
paymentPublicKey: Public key for the payment address
recipientAddress: Address to receive the minted ordinal
recipientPublicKey: Public key for the recipient address
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { psbt: string[] }

Broadcast Mint Transaction

Broadcasts a signed mint transaction.

const result = await inscrib3.drops.broadcastMint(
  id: string,
  signedPsbt: string[],
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop
signedPsbt: Array of signed PSBTs
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { txid: string }

Uploads Management

Get All Uploads

Retrieves all uploads for a drop.

const result = await inscrib3.drops.uploads.all(
  id: string,
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { files: string[] }

Update Uploads

Adds new files to a drop.

const result = await inscrib3.drops.uploads.update(
  id: string,
  files: File[],
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop
files: Array of File objects to upload
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { supply: string }

Remove Uploads

Removes files from a drop.

const result = await inscrib3.drops.uploads.remove(
  id: string,
  files: string[],
  address: string,
  message: string,
  signature: string
);

Parameters:

id: ID of the drop
files: Array of file names to remove
address: User's address for authentication
message: Authentication message
signature: Authentication signature

Returns: { supply: string }

Complete Example

Here's a complete example showing how to create a drop, upload files, and mint from it:

import sdk from '@inscrib3/sdk';

const inscrib3 = sdk();

// Authentication details
const userAddress = 'bc1q...';
const authMessage = 'Sign this message to authenticate with Inscrib3';
const authSignature = 'signature...';

// Create a drop
const createAndMint = async () => {
  try {
    // Step 1: Create a drop
    const dropResult = await inscrib3.drops.create(
      'My Ordinals Collection',
      'ORD',
      'A collection of unique digital artifacts on Bitcoin',
      iconFile,
      '10000',
      recipientAddress,
      recipientPublicKey,
      userAddress,
      authMessage,
      authSignature
    );
    
    console.log('Created drop with ID:', dropResult.id);
    
    // Step 2: Upload additional files
    const uploadResult = await inscrib3.drops.uploads.update(
      dropResult.id,
      additionalFiles,
      userAddress,
      authMessage,
      authSignature
    );
    
    console.log('Updated supply:', uploadResult.supply);
    
    // Step 3: Initiate minting
    const mintResult = await inscrib3.drops.mint(
      dropResult.id,
      paymentAddress,
      paymentPublicKey,
      recipientAddress,
      recipientPublicKey,
      userAddress,
      authMessage,
      authSignature
    );
    
    console.log('PSBTs to sign:', mintResult.psbt);
    
    // Step 4: Sign PSBTs (using your wallet or signing library)
    const signedPsbts = await signPsbts(mintResult.psbt);
    
    // Step 5: Broadcast the signed transaction
    const broadcastResult = await inscrib3.drops.broadcastMint(
      dropResult.id,
      signedPsbts,
      userAddress,
      authMessage,
      authSignature
    );
    
    console.log('Mint transaction ID:', broadcastResult.txid);
  } catch (error) {
    console.error('Error:', error);
  }
};

Error Handling

The SDK uses standard Promise-based error handling. It's recommended to wrap API calls in try-catch blocks:

try {
  const drops = await inscrib3.drops.all(address, message, signature);
} catch (error) {
  console.error('API Error:', error);
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. You'll get autocomplete and type checking out of the box when using TypeScript.

License

MIT

11 months ago

11 months ago

11 months ago

12 months ago

12 months ago