Skip to main content

​
JavaScript SDK

@apiosk/sdk is the official JavaScript client for the Apiosk gateway. It wraps discovery, the 402 Payment Required loop, and execution behind a small typed client so application code does not have to assemble the raw HTTP flow by hand. Use it when your software runs in a Node backend and you want gateway calls, typed payment errors, and optional automatic on-chain settlement in one package.

​
Install

npm install @apiosk/sdk
Requires Node 20 or newer (the SDK uses the global fetch). You can also inject your own fetch implementation through the constructor.

​
Quick start

import { ApioskClient } from "@apiosk/sdk";

const client = new ApioskClient();

const catalog = await client.listApis({ search: "diff", limit: 5 });
const metadata = await client.getMetadata("agent-json-diff");

const result = await client.execute("agent-json-diff", {
  before: { ok: true },
  after: { ok: false },
});

console.log(catalog.meta.total);
console.log(metadata.execute.default_operation);
console.log(result.result);
Discovery calls (listApis, getApi, getMetadata) are public and need no credentials. execute only needs credentials when the route is paid.

​
Auto-pay with x402

If you provide a Base wallet private key, the client automatically settles 402 Payment Required responses using Coinbase’s x402 packages and retries the call with the resulting proof. Your code just awaits the result. 
import { ApioskClient } from "@apiosk/sdk";

const client = new ApioskClient({
  privateKey: process.env.APIOSK_PRIVATE_KEY,
});

const response = await client.execute("agent-json-diff", {
  before: { ok: true },
  after: { ok: false },
});
The private key stays in your process and signs payments locally — it is never sent to the gateway.

​
Alternative auth modes

For dashboard-managed access, pass a connect token or an explicit authorization header instead of a private key: 
const client = new ApioskClient({
  connectToken: process.env.APIOSK_CONNECT_TOKEN,
});

const client = new ApioskClient({
  authorization: `Bearer ${process.env.APIOSK_BEARER_TOKEN}`,
});
If you already have an x-payment proof from your own payer flow, you can attach it directly with the xPayment option.

​
Constructor options

OptionPurpose
baseUrlGateway base URL. Defaults to https://gateway.apiosk.com.
privateKeyBase wallet key for automatic x402 settlement.
connectTokenDashboard connect token for managed-wallet access.
authorizationExplicit Authorization header value.
xPaymentA pre-built x-payment proof to attach as-is.
connectHeaderNameOverride the connect-token header name. Defaults to x-apiosk-connect-token.
headersExtra headers merged into every request.
fetchCustom fetch implementation (for non-global-fetch runtimes).

​
API surface

MethodMaps to
listApis(params)GET /v1/apis — search and paginate listings.
getApi(slug)GET /v1/apis/:slug — inspect one listing.
getMetadata(slug)GET /:slug/metadata — agent-native metadata.
execute(slug, input, options)POST /:slug/execute — default operation.
executeOperation(slug, operation, input, options)POST /:slug/execute with an explicit operation.
passthrough(slug, path, options)/:slug/*path — provider-specific shape.
// Explicit operation
const extracted = await client.executeOperation("graph-nexus-api", "extract", {
  text: "OpenAI partnered with Microsoft to scale AI infrastructure.",
});

// Passthrough for provider-specific routes
const raw = await client.passthrough("vision-flux-v4", "/v2/detect", {
  method: "POST",
  body: { image_url: "https://example.com/photo.jpg" },
});

​
Errors

The SDK throws typed errors so callers can branch on payment state:
ErrorWhen
ApioskErrorBase error class for all SDK failures.
ApioskHttpErrorAny non-2xx gateway response. Carries the response context.
ApioskPaymentRequiredErrorA 402 that could not be settled automatically.
ApioskPaymentRequiredError includes the parsed 402 body, so a caller that is not using the built-in EVM flow can inspect the accepted payment rails and attach its own proof. 
import { ApioskClient, ApioskPaymentRequiredError } from "@apiosk/sdk";

const client = new ApioskClient(); // no payer configured

try {
  await client.execute("agent-json-diff", { before: {}, after: {} });
} catch (err) {
  if (err instanceof ApioskPaymentRequiredError) {
    console.log(err.body.accepts); // payment requirements to satisfy
  }
}
The gateway client is intentionally separate from the merchant checkout UI:
  • @apiosk/checkout-core — shared checkout schema and intent helpers
  • @apiosk/checkout-web — plain HTML and custom-element checkout
  • @apiosk/checkout-react — React and Next.js apps
  • @apiosk/checkout-vue — Vue apps
  • apiosk (Python) — server-side intent creation, webhook verification, and status polling