Seller integration guide

Build with AgentPay

Turn an existing HTTPS API into a reviewable storefront for people and software agents—without handing AgentPay your wallet keys or deployment authority.

Development preview

The seller workflow is verified locally. Payments are limited to mock mode or Base Sepolia USDC testnet while AWS deployment and release verification remain in progress.

Quickstart

AgentPay uses a local connector as the only supported production- shaped MCP path. The connector exchanges your project key for a short-lived cloud capability; the key is never sent to/mcp directly.

The coding agent edits your repository using AgentPay MCP analysis and guidance. AgentPay MCP does not write repository files; it provides bounded configuration and verification tools, and cloud mutations remain subject to seller confirmation.

Your repositoryLocal connectorAgentPay cloudStorefront

1. Complete the prerequisites

Before key creation appears, the seller must have a verified account and profile, an active launch entitlement, a verified supported testnet payout address, and a reachable HTTPS service origin.

  • Verified seller identity
  • HTTPS fulfillment origin
  • Base Sepolia USDC destination
  • Active launch entitlement

2. Create a project key

Each apc2 key contains a fresh 256-bit secret from a cryptographically secure random generator. AgentPay shows the raw key once and stores only an HMAC-SHA-256 digest protected by a cloud-held pepper. Rotation creates a new random successor and revokes the previous key.

Keep it server-side.Store the key in your local secret environment. Never commit it, expose it through NEXT_PUBLIC_*, or paste it into client code.

Connect the MCP client

Configure Claude Code, Codex, or a generic MCP host to launch the pinned local connector over stdio. First download the exact versioned GitHub Release asset, verify its checksum and source provenance, and install it in the documented versioned local directory. This example uses Codex and a PowerShell session.

.codex/config.toml
[mcp_servers.agentpay]command = "node"args = ["C:\Users\SELLER\AppData\Local\AgentPay\mcp-connector\0.1.0\node_modules\@agentpay\local-mcp-connector\dist\cli.js"]env_vars = ["AGENTPAY_API_BASE_URL", "AGENTPAY_PROJECT_KEY"]required = true
PowerShell
$ConnectorEntry = Join-Path $env:LOCALAPPDATA "AgentPay\mcp-connector\0.1.0\node_modules\@agentpay\local-mcp-connector\dist\cli.js"if (-not (Test-Path -LiteralPath $ConnectorEntry)) { throw "Install the verified release artifact first." }$env:AGENTPAY_API_BASE_URL = "https://api.example.agentpay"$env:AGENTPAY_PROJECT_KEY = Read-Host "Paste the project key shown once" -MaskInputnode $ConnectorEntry --checkcodex

Replace the example API origin with the environment-specific origin shown in the seller dashboard and replace the exampleSELLER path with the installed connector path. Never substitute an npm registry command or mutable Git URL for the verified release artifact.

Generate reviewable changes

Start with a bounded prompt. The coding agent may inspect committed manifests and OpenAPI, identify an evidenced stack, install verification, and prepare tests. It cannot choose prices or payout addresses for you.

Prompt
Connect this project to AgentPay. Inspect only bounded committed manifests and OpenAPI, detect one maintained stack, propose sellable routes plus truthful SEO/AEO changes, install AgentPay request verification, and generate focused tests. Ask me for every exact price and payout destination. Never invent or change prices or payout addresses, publish, rotate credentials, or deploy without my explicit confirmation.

Review, confirm, then publish

  1. 01
    Review the diff

    Check routes, exact prices, verification middleware, discovery files, and tests.

  2. 02
    Confirm the exact mutation

    The seller dashboard issues a one-time grant bound to the reviewed operation and arguments.

  3. 03
    Run sandbox validation

    Verify payment gating, signatures, idempotency, metadata, and fulfillment before publication.

Understand the checkout path

Browser wallets and software agents enter the same immutable purchase-intent pipeline. AgentPay verifies the exact quote and finalized testnet payment, claims fulfillment once, then forwards a short-lived signed execution request to the seller.

Check payment compatibility

Read GET /v1/payment-capabilities before presenting payment. The development runtime currently enables exact x402 on Base Sepolia USDC only. Browser and agent buyers use the same immutable quote and payment path; card checkout is not enabled.

External buyer software can call POST /v1/payment-capabilities/compatibility to compare its declared x402 support with the running environment. A compatible result names the required headers and the separate buyer-agent key boundary. Seller project keys are never buyer credentials and must not be sent to commerce endpoints.

HTTP
POST /v1/payment-capabilities/compatibilityContent-Type: application/json{  "schemaVersion": "agentpay.external-buyer-capabilities.v1",  "capabilities": [{    "protocol": "x402",    "x402Version": 2,    "scheme": "exact",    "network": "eip155:84532",    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"  }]}
01Discover

Read hosted storefront metadata, signed manifests, or llms.txt. Discovery is never authorization.

02Pay

Authorize the exact Base Sepolia USDC quote. Underpayment and overpayment are rejected.

03Fulfill

AgentPay forwards one signed request only after final payment and an atomic transaction claim.

04Verify

Receipts, evidence, transaction state, and seller-reported refund records remain in the control plane.

Maintained stacks

Stack detection must be backed by bounded repository evidence. The current maintained matrix contains these 21 recipes.

  • Next.js
  • React/Vite + Node API
  • Remix
  • Nuxt
  • SvelteKit
  • Astro
  • Express
  • Fastify
  • NestJS
  • Go net/http
  • Gin
  • Echo
  • Fiber
  • FastAPI
  • Starlette
  • Flask
  • Django
  • ASP.NET Core
  • Spring Boot
  • Rails
  • Laravel

Security model

AgentPay controls

Identity, entitlement, key validation, publication, payment verification, transaction state, signatures, receipts, and evidence.

You control

Your repository, service deployment, exact prices, payout destination, wallet authorization, and upstream business logic.

The agent can propose

Repository changes, candidate routes, verification setup, tests, and truthful SEO/AEO files.

The agent cannot approve

Prices, payout changes, publication, credential rotation, or production deployment.

Read the security overview

Current limits

  • AgentPay is not yet a production-ready paid service.
  • Payments are mock mode or Base Sepolia USDC x402 testnet only.
  • Card checkout, mainnet, multiple assets, shipping, tax, and physical inventory are deferred.
  • The global marketplace directory and ranking are deferred.
  • Technical SEO and AEO improve discoverability but never guarantee ranking, traffic, or sales.
Ready to prepare a seller project?

Complete onboarding first; AgentPay reveals connector setup only after every server-authoritative prerequisite passes.

Create account