Axios

The @sapiom/axios package wraps your Axios instance with automatic payment handling and authorization.

---

Installation

npm

bash npm install @sapiom/axios axios

pnpm

bash pnpm add @sapiom/axios axios

yarn

bash yarn add @sapiom/axios axios

Note

Peer Dependency: Requires axios >= 1.0.0

---

Basic Setup

Wrap your Axios instance with Sapiom handling:

import axios from "axios";
import { withSapiom } from "@sapiom/axios";

const client = withSapiom(
  axios.create({
    baseURL: "https://api.example.com",
  }),
  {
    apiKey: process.env.SAPIOM_API_KEY,
  }
);

// Automatically handles 402 payment flows and authorization
const response = await client.get("/premium-endpoint");
console.log(response.data);

---

Configuration

All configuration options for withSapiom:

import axios from "axios";
import { withSapiom } from "@sapiom/axios";

const client = withSapiom(
  axios.create({
    baseURL: "https://api.example.com",
  }),
  {
    // Optional - Automatically uses process.env.SAPIOM_API_KEY if not provided
    apiKey: process.env.MY_CUSTOM_SAPIOM_KEY,

    // Optional - Control
    enabled: true, // Enable Sapiom handling (default: true)
    failureMode: "open", // 'open' | 'closed' (default: 'open')
    // 'open': Allow requests if Sapiom fails (prioritizes availability)
    // 'closed': Block requests if Sapiom fails (prioritizes security)

    // Optional - Default metadata (applied to all requests)
    agentName: "my-agent", // Agent identifier
    agentId: "agent-123", // Agent UUID or numeric ID
    serviceName: "my-service", // Service name for transactions
    traceId: "trace-xyz", // Internal trace UUID
    traceExternalId: "ext-456", // External trace identifier
  }
);

Configuration Options

apiKey string required

Your Sapiom API key. Can also be set via SAPIOM_API_KEY environment variable

enabled boolean default: true

Enable Sapiom handling. When disabled, requests pass through without Sapiom processing

failureMode 'open' | 'closed' default: 'open'

Control behavior when Sapiom operations fail: - 'open': Allow requests to proceed (prioritizes availability) - 'closed': Block requests (prioritizes security)

agentName string

Agent identifier for tracking and attribution

agentId string | number

Agent UUID or numeric ID

serviceName string

Service name for transactions

traceId string

Internal trace UUID for request correlation

traceExternalId string

External trace identifier for integration with external systems

---

Per-Request Overrides

Override configuration for individual requests using the __sapiom property:

// Disable Sapiom for a specific request
await client.get("/public-endpoint", {
  __sapiom: { enabled: false },
});

// Override metadata for a specific request
await client.post("/api/resource", data, {
  __sapiom: {
    serviceName: "different-service",
    actionName: "custom-action",
    traceExternalId: "ext-789",
  },
});

---

Payment Handling

The wrapper automatically handles 402 Payment Required responses:

import axios from "axios";
import { withSapiom } from "@sapiom/axios";

const client = withSapiom(
  axios.create({
    baseURL: "https://api.example.com",
  }),
  {
    apiKey: process.env.SAPIOM_API_KEY,
  }
);

try {
  // Automatically handles 402 payment flows
  const response = await client.get("/premium-endpoint");
  console.log(response.data);
} catch (error) {
  // Payment errors will be handled by Sapiom
  console.error("Request failed:", error);
}

---

Environment Variables

Automatically reads from environment:

• SAPIOM_API_KEY (required)
• SAPIOM_BASE_URL or SAPIOM_API_URL (optional)
• SAPIOM_TIMEOUT (optional, in milliseconds)

---

Best Practices

Use Environment Variables

Never hardcode API keys:

// ✅ Good
const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
});

// ❌ Bad
const client = withSapiom(axios.create(), {
  apiKey: "sk_...",
});

Choose Appropriate Failure Mode

// For production APIs - prioritize availability
const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
  failureMode: "open", // Requests proceed even if Sapiom fails
});

// For sensitive operations - prioritize security
const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
  failureMode: "closed", // Requests blocked if Sapiom fails
});

---

Next Steps

Fetch API Native fetch integration

Node.js HTTP Native http/https integration