examples

Sapiom SDK Examples

Quick start guide for integrating Sapiom into your AI agents.

Prerequisites

• Node.js 18+
• An invite to Sapiom (check your email for signup link to https://app.sapiom.ai/)

Setup

1. Get your Sapiom API Key

1. Sign up / log in at https://app.sapiom.ai/
2. Go to Settings (gear icon)
3. Create a new API key
4. Copy the key - this is your SAPIOM_API_KEY

2. Configure your environment

# Pick an example to try (axios is simplest)
cd axios

# Install dependencies
npm install

# Copy the environment template
cp ../.env.example .env

Edit .env and fill in your keys:

SAPIOM_API_KEY=your-key-from-step-1
SAPIOM_API_URL=https://api.sapiom.ai

# For axios/fetch/node-http examples:
DUMMY_SERVER_URL=https://x402-demo.sapiom.ai

# For langchain examples only:
ANTHROPIC_API_KEY=sk-ant-your-key

Note: The DUMMY_SERVER_URL points to a public demo server that simulates paid API endpoints. The default URL in .env.example is ready to use.

3. Run an example

# Default: runs free endpoints only (no balance required)
npm start

# Or explicitly:
npm run free    # Free endpoints (authorization only)
npm run full    # All endpoints (requires Sapiom balance for payments)

Start with npm start - this uses free endpoints and doesn't require a balance. You can test:

• Basic SDK integration
• Authorization tracking
• Usage rules

If you have a balance in your account (check https://app.sapiom.ai/), you can run npm run full to test paid endpoints and spending rules.

Verify it's working

After running an example, check the Sapiom dashboard:

1. Activity (https://app.sapiom.ai/activity) - See all transactions from your agent
2. Agents (https://app.sapiom.ai/agents) - Your agent should appear here
3. Services (https://app.sapiom.ai/services) - See the services your agent accessed

Test authorization denial

To see how Sapiom handles policy violations:

1. Go to Rules (https://app.sapiom.ai/rules)
2. Click Add New Rule
3. Create a usage limit:
   • Name: "Test Usage Limit"
   • Limit Type: Usage
   • Maximum: 1 call
   • Time Period: Per Run
   • Services: All Services
   • Agents: All Agents
4. Click Create Rule
5. Run the example again

On the second request, you should see an AuthorizationDeniedError - this means Sapiom blocked the request based on your rule.

Available Examples

Example	Package	Best for
axios/	@sapiom/axios	Existing Axios codebases
fetch/	@sapiom/fetch	Native fetch API users
node-http/	@sapiom/node-http	Raw Node.js HTTP
langchain-classic/	@sapiom/langchain-classic	LangChain v0.3.x with tool wrappers

Note: The langchain/ example is for LangChain v1.x. Use langchain-classic/ if you're on LangChain v0.3.x.

Start with axios/ or fetch/ - they're the simplest to understand.

About the Demo Server

The examples connect to a demo server that simulates real-world APIs with payment requirements. This server implements the x402 payment protocol - an HTTP standard where APIs can require micropayments.

How it works:

1. Your code makes a normal HTTP request (e.g., POST /api/sms)
2. The server returns 402 Payment Required with pricing info
3. The Sapiom SDK automatically handles the payment
4. The server validates payment and returns the response

You don't need to understand the x402 protocol - the Sapiom SDK handles it transparently. Your code just makes normal HTTP requests.

The demo server simulates a marketing platform with:

• CRM endpoints - Customer data (free, but requires authorization)
• SMS endpoints - Send messages (paid per message)
• Analytics endpoints - Campaign metrics (paid + authorization)

Demo Server Endpoints

The demo server (DUMMY_SERVER_URL) provides these endpoints:

Free endpoints (no balance required)

Endpoint	Auth	Payment	Description
GET /api/public/time	No	No	Current server time
GET /api/public/status	No	No	Server health check
GET /api/crm/customers	Yes	No	Fetch customer list

Paid endpoints (require balance)

Endpoint	Auth	Payment	Description
POST /api/sms	No	$0.0075	Send SMS message
POST /api/campaigns/analytics	Yes	$0.05	Get campaign analytics

The Sapiom SDK handles all authorization and payment automatically - your code just makes normal HTTP requests.

Note: If you run npm run full without a balance, the paid requests will fail and show as "Denied" in the Activity dashboard (https://app.sapiom.ai/activity).

Troubleshooting

"SAPIOM_API_KEY environment variable is required"

• Make sure you copied .env.example to .env and filled in your API key

Connection refused / timeout

• Check that DUMMY_SERVER_URL is correct and the test server is running

AuthorizationDeniedError on first request

• Check your Rules in the dashboard - you may have a restrictive policy

Nothing showing in dashboard

• Verify your SAPIOM_API_KEY is correct
• Check the console output for errors

Questions?

Reach out to your Sapiom contact or email support@sapiom.ai