Get started with Marlin in five minutes

Install @marlin/sdk, create your first invoice, and share a hosted payment link — your customer pays in USDC, PYUSD, or USDG on Solana.

Marlin gives you a Stripe-like billing layer on Solana. This guide walks you through everything you need to go from a fresh account to a live invoice with a hosted checkout URL your customer can pay in USDC, PYUSD, or USDG.

1. Connect your wallet and create an account

   Go to the Marlin dashboard and click Connect wallet. Marlin uses Sign-In With Solana (SIWS), so you sign a message — no seed phrase, no gas. Any Solana wallet (Phantom, Backpack, Solflare) works.

   After signing in for the first time, Marlin creates a merchant account tied to your wallet address. You land on the dashboard home where you can see your revenue, customers, and invoices.

2. Generate an API key

   In the sidebar, go to Settings → API Keys and click Create key.

   Give the key a descriptive label (for example, backend-server) and copy the value shown — it starts with sk_live_ for production or sk_test_ for test mode. Store it in a secret manager or environment variable; you won’t be able to view it again.

   Never commit your API key to version control or expose it in client-side code. Treat it like a password.

3. Install the SDK

   Add @marlin/sdk to your project:

   npm

   npm install @marlin/sdk
   

   The SDK requires Node.js 20 or later and ships full TypeScript types — no separate @types package needed.

4. Create your first invoice

   Initialize the client with your API key, then call marlin.invoices.create. Pass a customerId and at least one line item. unitAmount is in the smallest denomination of the currency (cents for USD-pegged stablecoins).

   invoice.ts

   import { Marlin } from "@marlin/sdk";
   
   const marlin = new Marlin({ apiKey: process.env.MARLIN_API_KEY! });
   
   const invoice = await marlin.invoices.create({
     customerId: "cus_abc123",
     lineItems: [
       { description: "Pro Plan — May 2025", quantity: 1, unitAmount: 4900 },
     ],
   });
   
   console.log(invoice.id, invoice.paymentUrl);
   

   A successful call returns an Invoice object:

   {
     "id": "inv_01HZ3Q...",
     "object": "invoice",
     "status": "open",
     "currency": "USDC",
     "amount": 4900,
     "amountPaid": 0,
     "amountRemaining": 4900,
     "paymentUrl": "https://checkout.marlin.dev/i/tok_..."
   }
   

   The paymentUrl is a fully hosted checkout page that is ready the moment the invoice is created. You can share it immediately — no additional setup required.

5. Share the payment URL

   Send invoice.paymentUrl to your customer however you like — email, Slack, in-app notification. The hosted checkout page:

   • Works with any Solana wallet via the wallet adapter
   • Accepts USDC, PYUSD, and USDG
   • Settles directly to your wallet on-chain
   • Updates the invoice status to paid automatically once the transaction confirms

   Marlin charges a flat 0.5% fee on settled payments. There are no monthly fees, no per-customer fees, and no charge on failed payments.

What’s next

Invoices

Learn about invoice statuses, line items, metadata, and voiding.

Accept payments

Handle payment confirmations, reconciliation, and multi-currency invoices.

Webhooks

Get notified in real time when invoices are paid, subscriptions change, and more.