SDKs and Programs

API or SDK?

Two things only the API can do:

• Draws. A draw from a Gumball or Jellybean made on mallow needs mallow's co-signature, and mallow co-signs only transactions its own draw builder made. See Draws go through mallow
• Scheduled bids. mallow places the bid for you later, so the record lives on mallow's side

Program Addresses

These are the mainnet addresses. Each one is the address in the program's source and in its published clients.

The same seven addresses hold a deployed program on devnet, checked on 12 October 2026.

A New artwork Gumball is the exception to the table. It runs on Metaplex's Core Candy Machine program, not on mallow Gumball, which draws pre-minted artworks only.

You don't have to take a sweepstake result on trust. The Sweepstake program decides every draw on chain, and Verifying a draw shows how to recompute one.

Token Mints

Program Clients

Each program has a client generated from its interface with Codama. A client holds the account decoders, the instruction builders, the address derivations, the error codes and the program address.

The JavaScript packages are on npm and the Rust crates are on crates.io.

npm install @mallow-labs/mallow-market @solana/kit@7

cargo add mallow-market-client

The smallest useful call reads a listing straight from the chain, with no API key:

import { address, createSolanaRpc } from "@solana/kit";
import {
  MALLOW_MARKET_ERROR__LISTING_EXPIRED,
  MALLOW_MARKET_PROGRAM_ADDRESS,
  fetchMaybeListingFromSeeds,
  getMallowMarketErrorMessage,
} from "@mallow-labs/mallow-market";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");

// Derives the listing PDA from the mint and decodes the account.
const listing = await fetchMaybeListingFromSeeds(rpc, { mint: address("<artwork-mint>") });
if (listing.exists) {
  console.log(listing.data.seller, listing.data.price); // price is a bigint
}

console.log(MALLOW_MARKET_PROGRAM_ADDRESS); // MMA7VebX8Pi5JrrvaTBBm7nW81sfCww7ZtLBBT1YCy8
console.log(getMallowMarketErrorMessage(MALLOW_MARKET_ERROR__LISTING_EXPIRED)); // error 6002

What to know before you depend on them:

• Solana Kit version. The Market, Auction, Rewards, Gumball and Jellybean clients are built for @solana/kit 7. The Sweepstake SDK pins @solana/kit 8.3.0
• Error messages. getMallowMarketErrorMessage and the same function in the other clients return the text only outside production builds. With NODE_ENV=production they return a placeholder, so log the code number as well
• Jellybean. The Kit client is marked as not yet tested in its repository. The Umi client is the tested one
• Market, Auction and Rewards have no README on npm. The types are the documentation. The Gumball client has a README with examples
• The Rust crates export the same pieces under generated, with the program address as a constant such as MALLOW_MARKET_ID

Other Packages

To verify a sweepstake draw from a script:

npm install @mallow-labs/mallow-sweepstake-sdk

import { verifyDrawManifest } from "@mallow-labs/mallow-sweepstake-sdk";

const manifest = await (await fetch("<manifest-url>")).json();
const verification = await verifyDrawManifest(manifest);

console.log(verification.offlineIntegrityValid, verification.errors);

This checks the manifest against itself and against the drand signature. To also check it against the chain, use the command on the Sweepstake page.

To use the token registry:

import { MALLOW_SOL, SMORES, TokenBySymbol } from "@mallow-labs/mallow-common";

console.log(SMORES); // smoEhMZMweWBnpd1QoU4ZjuVNBxMFchqy4NRMBbtW7V
console.log(MALLOW_SOL); // MLLWWq9TLHK3oQznWqwPyqD7kH4LXTHSKXK4yLz7LjD
console.log(TokenBySymbol["USDC"].decimals); // 6

These are the packages mallow's own apps are built on. Pin an exact version of any you depend on.

Gumball Metadata Template

When you load artworks into a New artwork Gumball on mallow.art, each image needs a JSON file beside it with the same name: 001.png and 001.json. Download the template for a still image or for an HTML artwork:

• metadata-example.json
• metadata-example-html.json

{
  "name": "My NFT #1",
  "description": "This is a description of my NFT",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Green"
    }
  ],
  "tags": ["photography", "my-custom-tag"]
}

• Leave out image. mallow writes image and properties from the files you upload
• For an HTML artwork, the uploaded image is the thumbnail and animation_url is the artwork
• Any other top-level field in the file is kept as it is
• The upload page checks every file before it uploads anything, and names the file and the field when one fails