apex-sdk

Publisher SDK for the APEX on-chain advertising network. Integrates AI applications with APEX's smart contracts on Base mainnet in 3 method calls.

Install

npm install apex-sdk

Quick Start

import { ApexSDK } from 'apex-sdk';

const apex = new ApexSDK({
  apiKey: process.env.APEX_API_KEY!,
  privateKey: process.env.PUBLISHER_KEY as `0x${string}`,
});

// 1. Register as a publisher (once, requires 0.005 ETH)
const identity = await apex.register('myagent.example.com');
console.log('Registered agent ID:', identity.agentId);

// 2. Get a semantically matched ad
const ad = await apex.getAd({ query: 'best running shoes for beginners' });

// 3. Confirm delivery (creates on-chain ad record for settlement)
if (ad) {
  const confirmation = await apex.confirmDelivery(ad.campaignId, userWalletAddress);
  console.log('Ad delivered, tx:', confirmation.transactionHash);
}

Ad Matching

The SDK uses the APEX API for semantic ad matching powered by OpenAI embeddings. Pass a query string to getAd() describing what your user is looking for — it can be a short keyword or a full sentence:

// Short keyword
const ad = await apex.getAd({ query: 'running shoes' });

// Natural language query
const ad2 = await apex.getAd({ query: 'what are the best budget travel destinations in southeast asia' });

// Detailed context from your application
const ad3 = await apex.getAd({ query: 'user is reading an article about home fitness equipment and asking for recommendations' });

Test Mode

Test mode lets you develop and test your integration without needing a real private key or ETH. It skips the whitelist check so you can iterate quickly on your ad-fetching flow.

import { ApexSDK } from 'apex-sdk';

const apex = new ApexSDK({
  apiKey: 'your-api-key',
  testMode: true,           // no private key needed
});

const ad = await apex.getAd({ query: 'running shoes' });
console.log(ad);

In test mode:

• No private key, ETH, or RPC connection is required
• getAd() still calls the APEX API for semantic matching — you get real ad results
• The whitelist check is skipped
• register() and confirmDelivery() are not mocked — they will fail if called, since test mode is for building your ad-fetching flow only

Configuration

const apex = new ApexSDK({
  apiKey: 'your-api-key',              // Required: API key for ad matching
  privateKey: '0x...',                 // Required (unless testMode is enabled)
  apiUrl: 'https://api.apexnetwork.app', // Optional: override API base URL
  rpcUrl: 'https://mainnet.base.org',   // Optional: defaults to Base mainnet
  testMode: false,                      // Optional: enable test mode for development
  contracts: {                          // Optional: override for testnet
    identityRegistry: '0x...',
    adRegistry: '0x...',
    campaignRegistry: '0x...',
  },
});

API

register(domain: string): Promise<RegisterResult>

Registers the publisher in the ERC-8004 IdentityRegistry. Idempotent — returns existing identity if already registered.

getAd(context?: AdContext): Promise<AdPayload | null>

Fetches a semantically matched ad from the APEX API. Read-only (no gas). Accepts optional query, topic, and categories for matching.

confirmDelivery(campaignId: bigint, userWallet?: string): Promise<DeliveryConfirmation>

Creates an on-chain ad record in the AdRegistry. The userWallet is encoded in metadata for validator attribution and CPA settlement.

Contract Addresses (Base Mainnet)

| Contract | Address | |----------|---------| | IdentityRegistry | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 | | AdRegistry | 0x5734e51dc16802b9724f4e1b877b39ccc01985c2 | | CampaignRegistry | 0x23ed7bbd9f4fb7d8fa98a13f1cce3484947cd689 |

License

Apache-2.0