Skip to main content

Quick Start

Get ads flowing in your AI agent in under 5 minutes.

1. Install​

npm install penguin-sdk

2. Get API keys​

import { PenguinClient } from 'penguin-sdk';

// One-time signup — no API key needed
const agent = await PenguinClient.signup({
  owner_email: 'you@example.com',
  agent_name: 'MyAgent',
});

console.log('Test key:', agent.api_key_test);
console.log('Live key:', agent.api_key_live);

Save these keys. Use am_test_* during development, switch to am_live_* for production.

3. Get your first ad​

import { PenguinClient } from 'penguin-sdk';

const client = new PenguinClient({
  apiKey: 'am_test_your_key_here',
});

// Pass the user's message as context
const response = await client.decideFromContext({
  context: 'What are the best project management tools for remote teams?',
});

if (response.status === 'fill') {
  for (const ad of response.units!) {
    console.log(`**${ad.creative.title}**`);
    console.log(ad.creative.body);
    if (ad.click_url) {
      console.log(`[${ad.creative.cta || 'Learn more'}](${ad.click_url})`);
    }
  }
} else {
  console.log('No relevant ads for this query');
}

That's it. Impressions are tracked automatically. Clicks go through HMAC-signed redirect URLs that handle billing.

4. Boost earnings with feedback​

After showing an ad, send the user's reaction to unlock prediction bonuses:

// Save the tracking token when you show an ad
const trackingToken = response.units![0].tracking_token;

// After the user responds to the ad
await client.sendFeedback({
  tracking_token: trackingToken,
  user_response: "That looks interesting, I'll check it out",
});

Accurate predictions earn you an extra 5–20% bonus on top of click revenue.

5. Go live​

When you're ready for production:

  1. Switch from am_test_* to am_live_* in your config
  2. That's it — same code, real revenue

Full integration example​

import { PenguinClient } from 'penguin-sdk';

const client = new PenguinClient({
  apiKey: process.env.PENGUIN_API_KEY!,
});

async function handleUserMessage(userMessage: string): Promise<string> {
  // 1. Get your AI's response (your existing logic)
  const aiResponse = await getAIResponse(userMessage);

  // 2. Check for relevant sponsored content
  const adResponse = await client.decideFromContext({
    context: userMessage,
    max_results: 1,
  });

  // 3. Append if relevant
  if (adResponse.status === 'fill') {
    const ad = adResponse.units![0];
    const sponsored = `\n\n---\n**${ad.creative.title}** — ${ad.creative.body}`;
    const cta = ad.click_url
      ? ` [${ad.creative.cta || 'Learn more'}](${ad.click_url})`
      : '';

    return aiResponse + sponsored + cta;
  }

  return aiResponse;
}

Next steps​