IP Asset

IPAssetClient

Methods

register
registerDerivative
registerDerivativeWithLicenseTokens
mintAndRegisterIpAssetWithPilTerms
registerIpAndAttachPilTerms
registerDerivativeIp
mintAndRegisterIpAndMakeDerivative
mintAndRegisterIp
registerPilTermsAndAttach
mintAndRegisterIpAndMakeDerivativeWithLicenseTokens
registerIpAndMakeDerivativeWithLicenseTokens
batchRegisterIpAssetsWithOptimizedWorkflows

Navigating Around the IPAssetClient

Because there are a lot of functions to interact with the 📜 Licensing Module, we have broken them down into a helpful chart so you can identify what you’re looking for, and then find the associated docs.

Function	Mint an NFT	Register IPA	Create License Terms	Attach License Terms	Mint License Token	Register as Derivative
register		✓
mintAndRegisterIp	✓	✓
registerIpAndAttachPilTerms		✓	✓	✓
mintAndRegisterIpAssetWithPilTerms	✓	✓	✓	✓
registerDerivativeIp		✓				✓
mintAndRegisterIpAndMakeDerivativeWithLicenseTokens	✓	✓				✓
registerIpAndMakeDerivativeWithLicenseTokens		✓				✓
mintAndRegisterIpAndMakeDerivative	✓	✓				✓
registerDerivative						✓
registerDerivativeWithLicenseTokens						✓
registerPilTermsAndAttach			✓	✓
registerPILTerms			✓
attachLicenseTerms				✓
mintLicenseTokens					✓

Red: IPAssetClient (this page)
Blue: LicenseClient

register

Registers an NFT as IP, creating a corresponding 🧩 IP Asset. If the given NFT was already registered, this function will return the existing ipId.

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`register`	`(request: RegisterRequest) => Promise<RegisterIpResponse>`

Parameters:

request.nftContract: The address of the NFT.
request.tokenId: The token identifier of the NFT.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.deadline: [Optional] The deadline for the signature in milliseconds. Defaults to 1000.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response = await client.ipAsset.register({
  nftContract: "0x041B4F29183317Fd352AE57e331154b73F8a1D73",
  tokenId: "12",
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});

console.log(
  `Root IPA created at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`
);

batchRegister

Batch registers an NFT as IP, creating a corresponding IP record.

Method	Type
`batchRegister`	`(request: BatchRegisterRequest) => Promise<BatchRegisterResponse>`

registerDerivative

Registers a derivative directly with parent IP’s license terms, without needing license tokens, and attaches the license terms of the parent IPs to the derivative IP.

The license terms must be attached to the parent IP before calling this function.

All IPs attached default license terms by default.

The derivative IP owner must be the caller or an authorized operator.

Method	Type
`registerDerivative`	`(request: RegisterDerivativeRequest) => Promise<RegisterDerivativeResponse>`

Parameters:

request.childIpId: The derivative IP ID.
request.licenseTermsIds: Array of license term IDs that authorize the creation of this derivative IP. Each ID must correspond positionally to a parent IP in the parentIpIds array, creating a one-to-one mapping. Story verifies on-chain that each specified license term permits derivative registration for its corresponding parent IP. Transaction fails if arrays don’t match in length or if terms don’t permit derivative creation.
request.parentIpIds: Array of parent IP IDs from which this derivative is created. Each parent IP must have corresponding license terms specified at the same index in the licenseTermsIds array that authorize the derivative relationship.
request.licenseTemplate: [Optional] The address of the license template to be used for the linking. For now, this can only be the PIL
request.maxMintingFee: [Optional] The maximum minting fee that the caller is willing to pay. If set to 0, then there is no no limit. Default: 0
request.maxRevenueShare: [Optional] The maximum revenue share percentage agreed upon between a child and parent when a child is registering as derivative. Must be between 0 and 100. Default: 100
request.maxRts: [Optional] The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Default: 100_000_000
request.txOptions: [Optional] The transaction options.

const response = await client.ipAsset.registerDerivative({
  childIpId: "0xC92EC2f4c86458AFee7DD9EB5d8c57920BfCD0Ba",
  parentIpIds: ["0xC92EC2f4c86458AFee7DD9EB5d8c57920BfCD0Ba"],
  licenseTermsIds: ["5"],
  txOptions: { waitForTransaction: true },
});

console.log(
  `Derivative IPA linked to parent at transaction hash ${response.txHash}`
);

registerDerivativeWithLicenseTokens

Registers a derivative with license tokens.

The derivative IP is registered with license tokens minted from the parent IP’s license terms.

The license terms of the parent IPs issued with license tokens are attached to the derivative IP.

The caller must be the derivative IP owner or an authorized operator.

Method	Type
`registerDerivativeWithLicenseTokens`	`(request: RegisterDerivativeWithLicenseTokensRequest) => Promise<RegisterDerivativeWithLicenseTokensResponse>`

Parameters:

request.childIpId: The derivative IP ID.
request.licenseTokenIds: The IDs of the license tokens.
request.maxRts: The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Recommended for simplicity: 100_000_000
request.txOptions: [Optional] The transaction options.

const response = await client.ipAsset.registerDerivativeWithLicenseTokens({
  childIpId: "0xC92EC2f4c86458AFee7DD9EB5d8c57920BfCD0Ba",
  licenseTokenIds: ["5"], // array of license ids relevant to the creation of the derivative, minted from the parent IPA
  txOptions: { waitForTransaction: true },
});

console.log(
  `Derivative IPA linked to parent at transaction hash ${response.txHash}`
);

mintAndRegisterIpAssetWithPilTerms

Mint an NFT from a collection, register it as an IP, attach metadata to the IP, and attach License Terms to the IP all in one function.

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`mintAndRegisterIpAssetWithPilTerms`	`(request: MintAndRegisterIpAssetWithPilTermsRequest) => Promise<MintAndRegisterIpAssetWithPilTermsResponse>`

Parameters:

request.spgNftContract: The address of the NFT collection.
request.allowDuplicates: [Optional] Set to true to allow minting IPs with the same NFT metadata. Default: true
request.licenseTermsData[]: The array of license terms to be attached. ⚠️ This function will fail if you pass in an empty array.
- request.licenseTermsData.terms: See the LicenseTerms type.
- request.licenseTermsData.licensingConfig: [Optional] See the LicensingConfig type. If none provided, it will default to the one shown here.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI: [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash: [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI: [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash: [Optional] The hash of the metadata for the IP NFT.
request.recipient: [Optional] The address of the recipient of the minted NFT.
request.txOptions: [Optional] The transaction options.

import { LicenseTerms } from "@story-protocol/core-sdk";
import { zeroAddress } from "viem";

const commercialRemixTerms: LicenseTerms = {
  transferable: true,
  royaltyPolicy: "0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E", // RoyaltyPolicyLAP address from https://docs.story.foundation/docs/deployed-smart-contracts
  defaultMintingFee: 0n,
  expiration: 0n,
  commercialUse: true,
  commercialAttribution: true,
  commercializerChecker: zeroAddress,
  commercializerCheckerData: zeroAddress,
  commercialRevShare: 50, // can claim 50% of derivative revenue
  commercialRevCeiling: 0n,
  derivativesAllowed: true,
  derivativesAttribution: true,
  derivativesApproval: false,
  derivativesReciprocal: true,
  derivativeRevCeiling: 0n,
  currency: "0x1514000000000000000000000000000000000000", // $WIP address from https://docs.story.foundation/docs/deployed-smart-contracts
  uri: "",
};

const response = await client.ipAsset.mintAndRegisterIpAssetWithPilTerms({
  spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc",
  licenseTermsData: [{ terms: commercialRemixTerms }],
  // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});

console.log(`
  Token ID: ${response.tokenId}, 
  IPA ID: ${response.ipId}, 
  License Terms ID: ${response.licenseTermsId}
`);

batchMintAndRegisterIpAssetWithPilTerms

Batch mint an NFT from a collection and register it as an IP.

Method	Type
`batchMintAndRegisterIpAssetWithPilTerms`	`(request: BatchMintAndRegisterIpAssetWithPilTermsRequest) => Promise<BatchMintAndRegisterIpAssetWithPilTermsResponse>`

registerIpAndAttachPilTerms

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`registerIpAndAttachPilTerms`	`(request: RegisterIpAndAttachPilTermsRequest) => Promise<RegisterIpAndAttachPilTermsResponse>`

Parameters:

request.nftContract: The address of the NFT collection.
request.tokenId: The ID of the NFT.
request.licenseTermsData[]: The array of license terms to be attached. ⚠️ This function will fail if you pass in an empty array.
- request.licenseTermsData.terms: See the LicenseTerms type.
- request.licenseTermsData.licensingConfig: [Optional] See the LicensingConfig type. If none provided, it will default to the one shown here.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI: [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash: [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI: [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash: [Optional] The hash of the metadata for the IP NFT.
request.deadline: [Optional] The deadline for the signature in milliseconds. Defaults to 1000.
request.txOptions: [Optional] The transaction options.

import { LicenseTerms } from "@story-protocol/core-sdk";
import { toHex, zeroAddress } from "viem";

const commercialRemixTerms: LicenseTerms = {
  transferable: true,
  royaltyPolicy: "0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E", // RoyaltyPolicyLAP address from https://docs.story.foundation/docs/deployed-smart-contracts
  defaultMintingFee: 0n,
  expiration: 0n,
  commercialUse: true,
  commercialAttribution: true,
  commercializerChecker: zeroAddress,
  commercializerCheckerData: zeroAddress,
  commercialRevShare: 50, // can claim 50% of derivative revenue
  commercialRevCeiling: 0n,
  derivativesAllowed: true,
  derivativesAttribution: true,
  derivativesApproval: false,
  derivativesReciprocal: true,
  derivativeRevCeiling: 0n,
  currency: "0x1514000000000000000000000000000000000000", // $WIP address from https://docs.story.foundation/docs/deployed-smart-contracts
  uri: "",
};

const response = await client.ipAsset.registerIpAndAttachPilTerms({
  nftContract: "0x041B4F29183317Fd352AE57e331154b73F8a1D73",
  tokenId: "12",
  licenseTermsData: [{ terms: commercialRemixTerms }],
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});
console.log(
  `Root IPA created at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`
);

registerDerivativeIp

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`registerDerivativeIp`	`(request: RegisterIpAndMakeDerivativeRequest) => Promise<RegisterIpAndMakeDerivativeResponse>`

Parameters:

request.nftContract: The address of the NFT collection.
request.tokenId: The ID of the NFT.
request.derivData: The derivative data to be used for registerDerivative.
- request.derivData.parentIpIds: The IDs of the parent IPs to link the registered derivative IP.
- request.derivData.licenseTermsIds: The IDs of the license terms to be used for the linking.
- request.derivData.maxMintingFee: [Optional] The maximum minting fee that the caller is willing to pay. If set to 0, then there is no no limit. Default: 0
- request.derivData.maxRevenueShare: [Optional] The maximum revenue share percentage agreed upon between a child and parent when a child is registering as derivative. Must be between 0 and 100. Default: 100
- request.derivData.maxRts: [Optional]The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Default: 100_000_000
- request.derivData.licenseTemplate: [Optional] The address of the license template to be used for the linking. For now, this can only be the PIL
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.deadline: [Optional] The deadline for the signature in milliseconds. Defaults to 1000.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response = await client.ipAsset.registerDerivativeIp({
  nftContract: "0x041B4F29183317Fd352AE57e331154b73F8a1D73", // your NFT contract address
  tokenId: "127",
  derivData: {
    parentIpIds: ["0xd142822Dc1674154EaF4DDF38bbF7EF8f0D8ECe4"],
    licenseTermsIds: ["1"],
  },
  // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});

console.log(
  `Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`
);

batchRegisterDerivative

Batch registers a derivative directly with parent IP’s license terms.

Method	Type
`batchRegisterDerivative`	`(request: BatchRegisterDerivativeRequest) => Promise<BatchRegisterDerivativeResponse>`

mintAndRegisterIpAndMakeDerivative

Mint an NFT from a collection and register it as a derivative IP without license tokens.

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`mintAndRegisterIpAndMakeDerivative`	`(request: MintAndRegisterIpAndMakeDerivativeRequest) => Promise<MintAndRegisterIpAndMakeDerivativeResponse>`

Parameters:

request.spgNftContract: The address of the NFT collection.
request.allowDuplicates: [Optional] Set to true to allow minting IPs with the same NFT metadata. Default: true
request.derivData: The derivative data to be used for registerDerivative.
- request.derivData.parentIpIds: The IDs of the parent IPs to link the registered derivative IP.
- request.derivData.licenseTermsIds: The IDs of the license terms to be used for the linking.
- request.derivData.maxMintingFee: [Optional] The maximum minting fee that the caller is willing to pay. If set to 0, then there is no no limit. Default: 0
- request.derivData.maxRevenueShare: [Optional] The maximum revenue share percentage agreed upon between a child and parent when a child is registering as derivative. Must be between 0 and 100. Default: 100
- request.derivData.maxRts: [Optional] The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Default: 100_000_000
- request.derivData.licenseTemplate: [Optional] The address of the license template to be used for the linking. For now, this can only be the PIL
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.recipient: [Optional] The address of the recipient of the minted NFT, default value is your wallet address.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response = await client.ipAsset.mintAndRegisterIpAndMakeDerivative({
  // an NFT contract address created by the SPG
  spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc",
  derivData: {
    parentIpIds: ["0xd142822Dc1674154EaF4DDF38bbF7EF8f0D8ECe4"],
    licenseTermsIds: ["1"],
  },
  // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});

console.log(
  `Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}, Token ID: ${response.tokenId}`
);

batchMintAndRegisterIpAndMakeDerivative

Batch mint an NFT from a collection and register it as a derivative IP without license tokens.

Method	Type
`batchMintAndRegisterIpAndMakeDerivative`	`(request: BatchMintAndRegisterIpAndMakeDerivativeRequest) => Promise<BatchMintAndRegisterIpAndMakeDerivativeResponse>`

mintAndRegisterIp

Mint an NFT from an SPGNFT collection and register it with metadata as an IP.

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`mintAndRegisterIp`	`(request: MintAndRegisterIpRequest) => Promise<RegisterIpResponse>`

Parameters:

request.spgNftContract: The address of the NFT collection.
request.allowDuplicates: [Optional] Set to true to allow minting IPs with the same NFT metadata. Default: true
request.recipient: [Optional] The address of the recipient of the minted NFT, default value is your wallet address.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.txOptions: [Optional] The transaction options.

import { toHex, Address, zeroAddress } from "viem";

const response = await client.ipAsset.mintAndRegisterIp({
  // an NFT contract address created by the SPG
  spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc",
  // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
  ipMetadata: {
    ipMetadataURI: "test-uri",
    ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
    nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
    nftMetadataURI: "test-nft-uri",
  },
  txOptions: { waitForTransaction: true },
});

console.log(
  `Completed at transaction hash ${response.txHash}, NFT Token ID: ${response.tokenId}, IPA ID: ${response.ipId}, License Terms ID: ${response.licenseTermsId}`
);

registerPilTermsAndAttach

Method	Type
`registerPilTermsAndAttach`	`(request: RegisterPilTermsAndAttachRequest) => Promise<RegisterPilTermsAndAttachResponse>`

Parameters:

request.ipId: The ID of the IP.
request.licenseTermsData[]: The array of license terms to be attached.
- request.licenseTermsData.terms: See the LicenseTerms type.
- request.licenseTermsData.licensingConfig: [Optional] See the LicensingConfig type. If none provided, it will default to the one shown here.
request.deadline: [Optional] The deadline for the signature in milliseconds. Defaults to 1000.
request.txOptions: [Optional] The transaction options.

import { LicenseTerms } from "@story-protocol/core-sdk";
import { zeroAddress } from "viem";

const commercialRemixTerms: LicenseTerms = {
  transferable: true,
  royaltyPolicy: "0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E", // RoyaltyPolicyLAP address from https://docs.story.foundation/docs/deployed-smart-contracts
  defaultMintingFee: 0n,
  expiration: 0n,
  commercialUse: true,
  commercialAttribution: true,
  commercializerChecker: zeroAddress,
  commercializerCheckerData: zeroAddress,
  commercialRevShare: 50, // can claim 50% of derivative revenue
  commercialRevCeiling: 0n,
  derivativesAllowed: true,
  derivativesAttribution: true,
  derivativesApproval: false,
  derivativesReciprocal: true,
  derivativeRevCeiling: 0n,
  currency: "0x1514000000000000000000000000000000000000", // $WIP address from https://docs.story.foundation/docs/deployed-smart-contracts
  uri: "",
};

const response = await client.ipAsset.registerPilTermsAndAttach({
  ipId: "0x4c1f8c1035a8cE379dd4ed666758Fb29696CF721",
  licenseTermsData: [{ terms: commercialRemixTerms }],
  txOptions: { waitForTransaction: true },
});
console.log(`License Terms ${response.licenseTermsId} attached to IP Asset.`);

mintAndRegisterIpAndMakeDerivativeWithLicenseTokens

Mint an NFT from a collection and register it as a derivative IP using license tokens

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`mintAndRegisterIpAndMakeDerivativeWithLicenseTokens`	`(request: MintAndRegisterIpAndMakeDerivativeWithLicenseTokensRequest) => Promise<RegisterIpResponse>`

Parameters:

request.spgNftContract: The address of the NFT collection.
request.allowDuplicates: [Optional] Set to true to allow minting IPs with the same NFT metadata. Default: true
request.maxRts: The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Recommended for simplicity: 100_000_000
request.licenseTokenIds: The IDs of the license tokens to be burned for linking the IP to parent IPs.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.recipient: [Optional] The address to receive the minted NFT, default value is your wallet address.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response =
  await client.ipAsset.mintAndRegisterIpAndMakeDerivativeWithLicenseTokens({
    spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc", // your SPG NFT contract address
    licenseTokenIds: ["10"],
    // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
    ipMetadata: {
      ipMetadataURI: "test-uri",
      ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
      nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
      nftMetadataURI: "test-nft-uri",
    },
    maxRts: 100_000_000, // default
    txOptions: { waitForTransaction: true },
  });

console.log(
  `Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}, Token ID: ${response.tokenId}`
);

registerIpAndMakeDerivativeWithLicenseTokens

Note that this function will also set the underlying NFT’s tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

Method	Type
`registerIpAndMakeDerivativeWithLicenseTokens`	`(request: RegisterIpAndMakeDerivativeWithLicenseTokensRequest) => Promise<RegisterIpResponse>`

Parameters:

request.nftContract: The address of the NFT collection.
request.tokenId: The ID of the NFT.
request.maxRts: The maximum number of royalty tokens that can be distributed to the external royalty policies. Must be between 0 and 100,000,000. Recommended for simplicity: 100_000_000
request.licenseTokenIds: The IDs of the license tokens to be burned for linking the IP to parent IPs.
request.ipMetadata: [Optional] The desired metadata for the newly minted NFT and newly registered IP.
- request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP.
- request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP.
- request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT.
- request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT.
request.deadline: [Optional] The deadline for the signature in milliseconds. Default is 1000.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response =
  await client.ipAsset.registerIpAndMakeDerivativeWithLicenseTokens({
    nftContract: "0x041B4F29183317Fd352AE57e331154b73F8a1D73", // your NFT contract address
    tokenId: "127",
    licenseTokenIds: ["10"],
    // https://docs.story.foundation/docs/ip-asset#adding-nft--ip-metadata-to-ip-asset
    ipMetadata: {
      ipMetadataURI: "test-uri",
      ipMetadataHash: toHex("test-metadata-hash", { size: 32 }),
      nftMetadataHash: toHex("test-nft-metadata-hash", { size: 32 }),
      nftMetadataURI: "test-nft-uri",
    },
    txOptions: { waitForTransaction: true },
  });

console.log(
  `Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`
);

batchRegisterIpAssetsWithOptimizedWorkflows

Batch register multiple IP assets in optimized transactions, supporting various registration methods. This method optimizes transaction processing by grouping related workflow requests together and intelligently selecting between multicall3 and SPG’s multicall based on compatibility.

The batching strategy significantly reduces gas costs and improves transaction throughput by minimizing the number of separate blockchain transactions. It also handles complex workflows like royalty token distribution automatically.

The method supports automatic token handling for minting fees:

If the wallet’s IP token balance is insufficient to cover minting fees, it automatically wraps native IP tokens into WIP tokens
It checks allowances for all required spenders and automatically approves them if their current allowance is lower than needed
These automatic processes can be configured through the wipOptions parameter

Supported registration methods:

mintAndRegisterIpAndMakeDerivative
mintAndRegisterIpAssetWithPilTerms
mintAndRegisterIpAndAttachPILTermsAndDistributeRoyaltyTokens
mintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokens
registerDerivativeIpAndAttachLicenseTermsAndDistributeRoyaltyTokens
registerIpAndAttachPilTerms
registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens
registerDerivativeIp

Method	Type
`batchRegisterIpAssetsWithOptimizedWorkflows`	`(request: BatchRegisterIpAssetsWithOptimizedWorkflowsRequest) => Promise<BatchRegisterIpAssetsWithOptimizedWorkflowsResponse>`

Parameters:

request.requests: Array of registration requests. Each request can be any of the supported registration method types.
request.wipOptions: [Optional] Configuration options for WIP token handling.
request.txOptions: [Optional] The transaction options.

import { toHex } from "viem";

const response =
  await client.ipAsset.batchRegisterIpAssetsWithOptimizedWorkflows({
    requests: [
      // Example of a mintAndRegisterIpAssetWithPilTerms request
      {
        spgNftContract: "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc",
        allowDuplicates: true,
        ipMetadata: {
          ipMetadataURI: "test-uri-1",
          ipMetadataHash: toHex("test-metadata-hash-1", { size: 32 }),
          nftMetadataHash: toHex("test-nft-metadata-hash-1", { size: 32 }),
          nftMetadataURI: "test-nft-uri-1",
        },
      },
      // Example of a registerDerivativeIp request
      {
        nftContract: "0x041B4F29183317Fd352AE57e331154b73F8a1D73",
        tokenId: "127",
        derivData: {
          parentIpIds: ["0xd142822Dc1674154EaF4DDF38bbF7EF8f0D8ECe4"],
          licenseTermsIds: ["1"],
        },
      },
    ],
    txOptions: { waitForTransaction: true },
  });

console.log("Batch registration results:", response.registrationResults);
if (response.distributeRoyaltyTokensTxHashes) {
  console.log(
    "Royalty distribution tx hashes:",
    response.distributeRoyaltyTokensTxHashes
  );
}

Get Started

SDK Reference

IPAssetClient

Methods

Navigating Around the IPAssetClient

register

batchRegister

registerDerivative

registerDerivativeWithLicenseTokens

mintAndRegisterIpAssetWithPilTerms

batchMintAndRegisterIpAssetWithPilTerms

registerIpAndAttachPilTerms

registerDerivativeIp

batchRegisterDerivative

mintAndRegisterIpAndMakeDerivative

batchMintAndRegisterIpAndMakeDerivative

mintAndRegisterIp

registerPilTermsAndAttach

mintAndRegisterIpAndMakeDerivativeWithLicenseTokens

registerIpAndMakeDerivativeWithLicenseTokens

batchRegisterIpAssetsWithOptimizedWorkflows

Get Started

SDK Reference

​IPAssetClient

​Methods

​Navigating Around the IPAssetClient

​register

​batchRegister

​registerDerivative

​registerDerivativeWithLicenseTokens

​mintAndRegisterIpAssetWithPilTerms

​batchMintAndRegisterIpAssetWithPilTerms

​registerIpAndAttachPilTerms

​registerDerivativeIp

​batchRegisterDerivative

​mintAndRegisterIpAndMakeDerivative

​batchMintAndRegisterIpAndMakeDerivative

​mintAndRegisterIp

​registerPilTermsAndAttach

​mintAndRegisterIpAndMakeDerivativeWithLicenseTokens

​registerIpAndMakeDerivativeWithLicenseTokens

​batchRegisterIpAssetsWithOptimizedWorkflows

IPAssetClient

Methods

Navigating Around the IPAssetClient

register

batchRegister

registerDerivative

registerDerivativeWithLicenseTokens

mintAndRegisterIpAssetWithPilTerms

batchMintAndRegisterIpAssetWithPilTerms

registerIpAndAttachPilTerms

registerDerivativeIp

batchRegisterDerivative

mintAndRegisterIpAndMakeDerivative

batchMintAndRegisterIpAndMakeDerivative

mintAndRegisterIp

registerPilTermsAndAttach

mintAndRegisterIpAndMakeDerivativeWithLicenseTokens

registerIpAndMakeDerivativeWithLicenseTokens

batchRegisterIpAssetsWithOptimizedWorkflows