Skip to main content

API Reference

This reference shows how to authenticate, create a payment session (get a link), and check payment status via the REST API. It also includes SDK usage patterns for Node.js and Python MCP servers.

Authentication​

Send your secret key in the Authorization header on every request.

Headers​

Authorization: Bearer <YOUR_SECRET_KEY>
Content-Type: application/json

Base URL​

https://api.walleot.com/v1

Keep your secret key on the server side only. Do not embed in client apps.

Create a payment session​

Creates a payment session and returns a session ID and checkout URL.

Endpoint​

POST /sessions

Request body​

  • amount (integer, required) – amount in cents
  • currency (string, required) – ISO 4217 currency code (e.g., "usd")
  • description (string, optional) – human-readable purpose
const response = await fetch('https://api.walleot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WALLEOT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 200,
    currency: 'usd',
    description: 'Pro feature unlock'
  })
});

const session = await response.json();
console.log(session.sessionId, session.url);

Response​

{
  "sessionId": "sess_123",
  "url": "https://pay.walleot.com/checkout/sess_123"
}

Notes​

  • The server expects amount in cents. (SDKs accept dollars and convert to cents for you.)
  • currency is lowercase in the underlying request.

Check payment status​

Retrieve the current status of a payment session.

Endpoint​

GET /sessions/{sessionId}
curl "https://api.walleot.com/v1/sessions/sess_123" \
  -H "Authorization: Bearer $WALLEOT_API_KEY"

Response​

{
  "status": "paid"
}

Complete payment flow example​

Here's how to create a session, get a payment link, and check status:

// 1. Create a payment session
const session = await fetch('https://api.walleot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WALLEOT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 200, // $2.00 in cents
    currency: 'usd',
    description: 'Premium feature unlock'
  })
});

const { sessionId, url } = await session.json();

// 2. Redirect user to payment link
console.log('Send user to:', url);

// 3. Check payment status (poll)
const checkStatus = async (sessionId) => {
  const response = await fetch(`https://api.walleot.com/v1/sessions/${sessionId}`, {
    headers: { 'Authorization': `Bearer ${process.env.WALLEOT_API_KEY}` }
  });
  const { status } = await response.json();
  return status; // "paid", "pending", "failed", etc.
};

// Poll for completion
const status = await checkStatus(sessionId);
if (status === 'paid') {
  console.log('Payment successful! Enable premium feature.');
}

SDK usage with MCP (automatic per-call pricing)​

For MCP servers, use the SDKs for automatic per-call charging:

import { Server } from "@modelcontextprotocol/sdk/server";
import { installWalleot, Mode } from "walleot";
import { z } from "zod";

const server = new Server({ name: "my-server", version: "0.0.1" });

installWalleot(server, {
  apiKey: process.env.WALLEOT_API_KEY!,
  mode: Mode.TWO_STEP, /* Alternatively, you can use mode.ELICITATION if MCP Client supports it  */
});

server.registerTool(
  "premium_analysis",
  {
    title: "Premium Analysis",
    description: "Advanced data analysis with AI.",
    inputSchema: { data: z.string() },
    price: { amount: 0.50, currency: "USD" }, // $0.50 per call
  },
  async ({ data }, extra) => {
    const result = await performAnalysis(data);
    return { content: [{ type: "text", text: result }] };
  }
);

Error Handling​

All API endpoints return standard HTTP status codes. Handle errors appropriately:

try {
  const response = await fetch('https://api.walleot.com/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WALLEOT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 200,
      currency: 'usd',
      description: 'Pro feature unlock'
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const session = await response.json();
  console.log(session.sessionId, session.url);
} catch (error) {
  console.error('Error creating session:', error);
}

Types & enums​

  • Mode: TWO_STEP (default), RESUBMIT, ELICITATION, PROGRESS, DYNAMIC_TOOLS
  • Node price shape: { amount: number, currency: string } (amount in USD dollars, converted under the hood)
  • Python decorator: @walleot.price(amount: float, currency: str) (dollars)

Payment Status Values​

Common status values returned by the API:

  • pending - Payment session created, awaiting payment
  • paid - Payment completed successfully
  • failed - Payment failed or was declined
  • expired - Payment session expired
  • cancelled - Payment was cancelled by user

Behavior​

  • New user: 2-click registration
  • Under threshold: auto-approved
  • Above threshold: one-tap 2FA prompt

Rate Limits​

API requests are rate limited. Current limits:

  • Sessions: 100 requests per minute per API key
  • Status checks: 1000 requests per minute per API key

Rate limit headers are included in responses:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Time when the rate limit resets

Next Steps​