{"id":13455709,"url":"https://github.com/nftstorage/metaplex-auth","last_synced_at":"2026-03-14T11:07:23.929Z","repository":{"id":37842202,"uuid":"425922135","full_name":"nftstorage/metaplex-auth","owner":"nftstorage","description":"**Notice: Uploads Decommissioned - Existing Data is Safe!**  This is a client library designed for Metaplex NFT uploads to NFT.Storage.  June 2024 Update: No new uploads, but all existing data is safe. Try the new NFT.Storage, which preserves data in long term Filecoin storage for a small fee. Go to app.nft.storage","archived":false,"fork":false,"pushed_at":"2024-07-03T04:38:06.000Z","size":776,"stargazers_count":19,"open_issues_count":0,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-28T23:33:12.709Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://nftstorage.github.io/metaplex-auth","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nftstorage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-08T16:58:39.000Z","updated_at":"2024-07-03T04:37:43.000Z","dependencies_parsed_at":"2024-10-28T23:40:40.697Z","dependency_job_id":null,"html_url":"https://github.com/nftstorage/metaplex-auth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fmetaplex-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fmetaplex-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fmetaplex-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fmetaplex-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nftstorage","download_url":"https://codeload.github.com/nftstorage/metaplex-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223640423,"owners_count":17178009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:01:09.805Z","updated_at":"2026-03-14T11:07:23.897Z","avatar_url":"https://github.com/nftstorage.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# metaplex-auth\n\nThis repo contains a client library for uploading data to [NFT.Storage](https://nft.storage) using a signature from a solana private key to authenticate the request.\n\nSee [SPEC.md](https://github.com/nftstorage/metaplex-auth/blob/main/SPEC.md) for details about the authentication scheme.\n\n## Product Decommission Notice\n\n### Important Update\n\nHello from NFT.Storage!\n\nAs of June 30, 2024, we have officially decommissioned NFT.Storage Classic uploads. This means that NFT.Storage Classic, including NFTUp, the Classic web app, Classic APIs, Classic SDK, and Pinning API, will no longer accept new uploads/pins.\n\n### What This Means for You\n\n**Service Termination:** NFT.Storage Classic will no longer accept new uploads. However, retrieval of existing data remains operational.\n\n**Data Access:** Don't forget, we're still keeping a copy of your NFT.Storage Classic data available in the NFT.Storage Gateway and in the decentralized Filecoin Network. However, over time, latency and availability may degrade.\n\n**Support:** We’ll be working with the newly formed NFT.Storage community to determine what changes, if any, will impact NFT.Storage Classic data latency and availability in the future. Join the community [Join the community](https://nft.storage/join-us) to have your say. We will keep you informed by email and on Twitter/X.\n\n### Transition to the New Version\n\nFor the new version of NFT.Storage, first mint your NFTs, then send us the NFT data—metadata and imagery CIDs, blockchain(s) minted on, contract address, and token IDs. We will preserve these in long-term Filecoin storage. Note that you need to upload the data to IPFS separately. Your NFTs will also be included in the NFT Token Checker, a tool for block explorers, marketplaces, and wallets to show verification that NFT collections, tokens, and CIDs are preserved by NFT.Storage.\n\n### Recommended Hot Storage Alternatives\n\nWe’re excited to announce our partnerships with Pinata and Lighthouse for hot storage solutions. As an NFT.Storage user, you support our platform when you choose Pinata and Lighthouse and use our referral links, helping to sustain our valuable public goods. [Learn more here](https://nft.storage/blog/announcing-our-new-partnerships-with-pinata-and-lighthouse).\n\n**Pinata:** Offers flexible plans and powerful, easy-to-use tools for managing your data on IPFS. Use code NFTSTORAGE50 at checkout to enjoy 50% off your first month. [Sign up today](https://pinata.cloud).\n\n**Lighthouse:** An IPFS provider with unique payment options for NFT longevity. They offer affordability and flexibility for all your IPFS needs, including a pay-once and store-forever option. [Sign up today](https://lighthouse.storage).\n\n### Contact Us\n\nFor any questions or assistance, contact us [contact us](https://nft.storage/contact-us). Together, we look forward to a promising future for NFT.Storage and the broader NFT ecosystem.\n\nBest regards,  \nThe NFT.Storage Team\n\n\n## Install\n\n```\nnpm install @nftstorage/metaplex-auth\n```\n\nor\n\n```\nyarn add @nftstorage/metaplex-auth\n```\n\n## Usage\n\nThis package is primarily intended to be used as a library in your JavaScript or TypeScript project.\n\nAPI reference docs can be found at https://nftstorage.github.io/metaplex-auth/\n\n### Creating a client\n\nThe main entry point into the API is the [NFTStorageMetaplexor class](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html), which provides methods for uploading files to NFT.Storage.\n\nTo create an `NFTStorageMetaplexor`, you'll need either a Solana private signing key or a `signMessage` function that can return a valid Ed25519 signature for a Solana account (for example, from a [wallet adapter](https://github.com/solana-labs/wallet-adapter)).\n\nThe methods for creating an `NFTStorageMetaplexor` also require a `mintingAgent` string.\n\nThe `mintingAgent` should identify the tool or platform used to prepare the upload.\n\nProjects using this library are free to choose their own value for this tag, however you should avoid changing the name over time, unless the project itself changes names (for example, due to a community fork or re-branding).\n\nFor personal projects or individuals creating tools that are not affiliated with a public platform, please set the value to a URL for your code repository. If your code is not yet public, please create a repository containing a description of the project and links to its public-facing interface.\n\nExamples of suitable values:\n\n- `\"metaplex/candy-machine-cli\"`\n- `\"metaplex/js-sdk\"`\n- `\"magiceden/mint-authority\"`\n- `\"https://github.com/samuelvanderwaal/metaboss\"`\n\nYou may also optionally pass an `agentVersion` string, to differentiate between different versions of your project.\n\n#### With secret key\n\nThe [`NFTStorageMetaplexor.withSecretKey` static method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#withSecretKey) accepts a `Uint8Array` containing a secret Ed25519 signing key.\n\nIt also optionally accepts an options object that can be used to set some metadata about the request. Most importantly, you should set the `solanaCluster` option to the cluster you intend to mint on. If not provided, it will default to `devnet`.\n\n```js\nimport { NFTStorageMetaplexor } from '@nftstorage/metaplex-auth'\n\nconst key = loadKeyFromSomewhere()\nconst client = NFTStorageMetaplexor.withSecretKey(key, {\n  solanaCluster: 'mainnet-beta',\n  mintingAgent: 'my-awesome-tool',\n})\n```\n\n#### With wallet adapter\n\nIf you're using a [wallet adapter](https://github.com/solana-labs/wallet-adapter) that supports the `signMessage` function, you can use it with the [`NFTStorageMetaplexor.withSigner` static method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#withSigner) by passing in the `signMessage` function and the public key.\n\n```js\nimport { NFTStorageMetaplexor } from '@nftstorage/metaplex-auth'\nimport { useWallet } from '@solana/wallet-adapter-react'\n\nconst MyComponent = () =\u003e {\n  const { publicKey, signMessage } = useWallet()\n  const client = NFTStorageMetaplexor.withSigner(signMessage, publicKey, {\n    solanaCluster: 'mainnet-beta',\n    mintingAgent: 'my-awesome-tool',\n  })\n}\n```\n\n### Uploading Metaplex NFTs\n\nTo assist with uploading Metaplex NFTs, this package includes support for loading [Metaplex NFT metadata](https://docs.metaplex.com/nft-standard) and uploading files that are referenced within.\n\nThe `storeNFT` methods will validate the metadata using a JSON schema to catch any formatting errors before upload.\n\n**Please note** that the schema validation code has not been widely tested yet on real-world NFT data and may be too restrictive. If you believe that it is rejecting valid metadata, please [open an issue](https://github.com/nftstorage/metaplex-auth/issues/new).\n\nIf you're using node.js, you can use the [NFTStorageMetaplexor.storeNFTFromFilesystem method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#storeNFTFromFilesystem) to load NFT data from disk and upload it in one operation.\n\n```js\nasync function uploadNFT(pathToMetadataJson) {\n  const key = loadKeyFromSomewhere()\n  const client = NFTStorageMetaplexor.withSecretKey(key)\n\n  const result = await client.storeNFTFromFilesystem(pathToMetadataJson)\n}\n```\n\nIf you're running in a browser, you'll need to use the [`prepareMetaplexNFT` function](https://nftstorage.github.io/metaplex-auth/modules.html#prepareMetaplexNFT), which accepts metadata as a JS object and takes `File` objects containing image and other asset data. The resulting [`PackagedNFT` object](https://nftstorage.github.io/metaplex-auth/interfaces/PackagedNFT.html) can be passed into the [storePreparedNFT method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#storePreparedNFT).\n\n#### File references\n\nThe `prepareMetaplexNFT` and `storeNFTFromFilesystem` methods will upload the `image`, `animation_url` and any files contained in `properties.files` if they contain valid file references.\n\nIn the case of `prepareMetaplexNFT`, the provided `imageFile` parameter will be uploaded, along with any `additionalAssetFiles`. The `image` field in the metadata will be replaced with an HTTP gateway URL to the uploaded image. Likewise, if the `animation_url` field contains the name of one of the `additionalAssetFiles`, the field will be replaced with a gateway URL.\n\nAll entries in `properties.files` will likewise be replaced with IPFS links if the `uri` field contains the filename of any of the uploaded files. Each uploaded file will contain _two_ entries in the final metadata: one containing an HTTP gateway URL with the `cdn` flag set to `true`, and one location-independent `ipfs://` URI with `cdn` set to `false`. This should allow clients to fetch content over HTTP while still preserving a location-independent link that doesn't depend on a single gateway.\n\nWhen using `storeNFTFromFilesystem` on node.js, the same rules apply, however you don't need to pass in `File` objects for each asset. Instead, you can set the `image` field (and optionally, `animation_url`) to a file path relative to the metadata JSON file, and the image data will be loaded from disk. Likewise, any entries in `properties.files` whose `uri` contains a valid file path will be uploaded, and the entry will be replaced with two IPFS links as with `prepareMetaplexNFT`.\n\n### Uploading files\n\nYou can upload arbitrary files using the [storeDirectory method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#storeDirectory). It accepts an `Iterable` of `File` objects and bundles them into an IPFS directory listing, returning the root CID of the stored directory.\n\n```js\nasync function uploadFiles(files) {\n  const key = loadKeyFromSomewhere()\n  const client = NFTStorageMetaplexor.withSecretKey(key)\n\n  const cid = await client.storeDirectory(files)\n  console.log(\n    `Stored ${files.length} file(s). Check them out at https://${cid}.ipfs.nftstorage.link`\n  )\n}\n```\n\nNote that the returned CID links to a directory object containing the files. If you want to link to individual files within the directory, you must append the filename to the result:\n\n```js\nasync function uploadFiles(files) {\n  const key = loadKeyFromSomewhere()\n  const client = NFTStorageMetaplexor.withSecretKey(key)\n\n  const cid = await client.storeDirectory(files)\n\n  // make HTTP gateway links using the nftstorage.link gateway\n  const gatewayBaseUrl = new URL(`https://${cid}.ipfs.nftstorage.link`)\n  const gatewayLinks = files.map((f) =\u003e new URL(f.name, gatewayBaseUrl))\n\n  // make gateway-agnostic IPFS uris:\n  const uriBase = new URL(`ipfs://${cid}`)\n  const ipfsURIs = files.map((f) =\u003e new URL(f.name, uriBase))\n}\n```\n\n### Uploading CAR files\n\nUnder the hood, all the upload methods encode data into IPFS Content Archives (CARs) before uploading.\n\nIf you already have CAR-formatted data, you can upload it with the [storeCar method](https://nftstorage.github.io/metaplex-auth/classes/NFTStorageMetaplexor.html#storeCar).\n\nThis may be useful if you have already imported your data into IPFS, or if you want to have more control over the object graph, for example, because you want to use [IPLD](https://ipld.io) to store structured data.\n\nThe `storeCar` method accepts a `CarReader` from the [@ipld/car package](https://github.com/ipld/js-car).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnftstorage%2Fmetaplex-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnftstorage%2Fmetaplex-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnftstorage%2Fmetaplex-auth/lists"}