APS Documentation

Build with the APS MCP

This guide walks through everything you need to orchestrate trustless model invocations secured by x402 payments. Start locally in demo mode, then flip the switches for production networks, facilitators, and persistent storage.

Quickstart

From repo to verified inference in four focused steps.

Install & configure

Clone the repository, copy `.env.example` to `.env`, and fill Solana RPC, wallet, and optional Supabase credentials.

cp apps/mcp-server/.env.example apps/mcp-server/.env

Launch the MCP server

Run the mock-ready server locally with hot reload. The demo catalog, x402 mocks, and Vitest suite ship by default.

cd apps/mcp-server && pnpm dev

Generate a demo token

Request a payment quote, then exchange it for an x402-compatible demo token before invoking a model.

curl -X POST http://localhost:3333/models/demo-flan-http/payment-token

Invoke your first model

Send the token via the `X-PAYMENT` header and payload. The server verifies, runs inference, and returns settlement metadata.

curl -X POST http://localhost:3333/invoke \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <demo-token>" \
  -d '{"model_id":"demo-flan-http","input":"Summarize the MCP.","payment_tx":"<demo-token>"}'

HTTP API surface

Every endpoint returns JSON. Prefix with your deployment URL (default: http://localhost:3333).

Method	Path	Purpose
GET	/health	Readiness probe for the MCP server.
GET	/models	Returns the merged catalog (persistent storage + demo models).
GET	/models/:id/payment-requirement	Builds an x402 payment quote with network, asset, timeout, and fee payer details.
POST	/models/:id/payment-token	Generates a demo payment token when the signer is configured or uses the mock ledger.
POST	/invoke	Verifies the payment token (mock or real), performs caching, triggers the model invocation, and records the transaction.
GET	/transaction/:id	Fetches settlement metadata for a previously confirmed invocation.

x402 payment flow

Understand the lifecycle of a single paid inference.

Discover

Query `/models` to identify an available model and inspect price, network, and metadata.

Quote

Use `/models/:id/payment-requirement` to obtain the x402 requirement payload and asset definition.

Sign

Either call `/models/:id/payment-token` in demo mode or craft your own x402 token using the quoted requirement.

Invoke

POST `/invoke` with the `X-PAYMENT` header. The MCP verifies and settles the token before launching inference.

Audit

Retrieve `/transaction/:id` for a structured view of the settlement proof, payer, asset, and amounts.

Project highlights

APS MCP is the backbone for a trustless agent platform. Here is why the project exists and how you can extend it.

Why APS MCP?

APS wraps the Model Context Protocol with verifiable payments. Agents can trust every inference thanks to x402 settlement metadata.

Batteries included

Mock ledger, Solana verifier, Supabase storage hooks, Vitest suites, and a modern landing page help you ship quickly.

Production ready

Env-driven configuration, facilitator integration, and HTTP models make it straightforward to migrate from demo to mainnet.