Docs Surfaces Registry Advertisers Privacy Support Sign in

SDK quickstart

Add one sponsor card to an open-source software surface.

Install the SDK, call one function, and add a clearly labeled sponsor card to a real developer moment: CLI output, an agent run summary, an MCP setup page, a template handoff, a plugin panel, or a local app. TipCLI handles matching, review gates, privacy rules, and payout evidence. The SDK never reads source code, terminal logs, `.env` files, or dependency manifests.

Create project Sponsor developer tools Privacy promise

Where it belongs

Human-visible CLI, agent, MCP, template, plugin, or local-app moments where a labeled card will not block work.

What it can earn

Only eligible, verified paid sponsor delivery after project approval, campaign review, and payout readiness. Estimates are not payable balances.

What stays out

No terminal logs, source code, environment variables, cookies, fingerprints, or projected earnings presented as payable balances.

Install

Start with the package.

Create a project first so the dashboard can give you a publisher key and project-specific snippet.

pnpm add @tipcli/sdk

TIPCLI_PUBLISHER_KEY=db_live_...

Private launch path that works now

Dashboard key, reviewed project, non-payable tests.

Create the project while signed in, copy the dashboard snippet, and test the selected surface. Treat local renders as non-payable integration checks until eligibility, campaign match, and payout readiness are complete.

Public npm path

Verify registry access before launch traffic.

Use pnpm npm:publish:check to confirm the public npm install smoke for @tipcli/sdk. Public package access does not make test renders payable.

Use

Add one call.

Put the card where it makes sense: CLI startup, dev server output, agent run summary, MCP health page, template handoff, plugin panel, or another reviewed developer surface.

import { showSponsorCard } from "@tipcli/sdk";

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "cli-startup",
  category: "frontend",
});

Integration note

The public package is published as @tipcli/sdk. During integration checks, use your dashboard snippet and treat local renders as non-payable until project review, campaign match, and payout readiness are complete.

Surface examples

The API stays the same. Choose a surface label that describes the human-visible placement and keep sponsor content out of generated code, hidden prompts, MCP tool responses, and machine-readable logs.

CLI startup

Use a startup or command-complete moment where a labeled sponsor card will not block the command.

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "cli-startup",
  category: "devops",
});

Agent run summary

Use a human-readable run summary, not hidden agent context or generated code.

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "agent-run-summary",
  category: "ai",
});

MCP server health

Use setup output, a health page, or inspector UI. Do not inject sponsors into MCP tool responses.

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "mcp-server-health",
  category: "ai",
});

Template post-install

Use the handoff screen after a starter/template creates a project.

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "template-postinstall",
  category: "frontend",
});

Local dashboard

Use a local app or dev-server dashboard where the sponsor card is clearly labeled.

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "local-dashboard",
  category: "infra",
});

What the SDK sends

A sponsor request contains the publisher key, surface, category, SDK version, session ID, and non-payable delivery flags for CI, fixture, disabled, or internal runs. It does not include project files, command output, user identity, cookies, or device fingerprints.

The SDK records delivery events for reviewed sponsor cards. It does not create earnings by itself, and test traffic is not payable.

Before you count delivery as payable

Local testing proves rendering only. Paid delivery starts after your project is reviewed, the integration uses a live publisher key, a paid reviewed campaign matches the project, and payout readiness is clear in the dashboard.

1. Create projectUse the dashboard to create a project and copy the one-time publisher key.
2. Test safelyUse local API overrides, CI, disabled mode, or fixture/internal delivery for non-payable tests.
3. Pass reviewTipCLI reviews the repo, placement surface, usage signal, and payout contact.
4. Serve live trafficOnly eligible projects with live delivery and paid reviewed campaigns can create payout evidence.

CI-safe

The SDK returns immediately when process.env.CI is set.

User opt-out

Developers can set TIPCLI_DISABLED=1.

Silent failure

Network errors, timeouts, and API failures never break your CLI.

Minimal fields

The SDK sends publisherKey, surface, category, sdkVersion, sessionId, and non-payable delivery flags for CI/test/disabled runs.

Stripe Connect payouts

Dashboard payout readiness uses real campaign terms and verified impressions. Stripe Connect is the primary launch payout path; manual transfer is an operator fallback only.

Separate balance states

Gross delivery value, verified payable, pending payout, and paid payout are separate states so projected money is never presented as money owed.

Payout policy

Before enabling paid delivery, read how TipCLI treats verified impressions, excluded traffic, Stripe Connect payout readiness, and the manual fallback rules.

Read payout policy Ask support