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.
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.
Get started
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.
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.
NEXT_PUBLIC_*, or paste it into client code.Core workflow
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.
[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$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 --checkcodexReplace 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.
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
- 01Review the diff
Check routes, exact prices, verification middleware, discovery files, and tests.
- 02Confirm the exact mutation
The seller dashboard issues a one-time grant bound to the reviewed operation and arguments.
- 03Run sandbox validation
Verify payment gating, signatures, idempotency, metadata, and fulfillment before publication.
Runtime
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.
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" }]}Read hosted storefront metadata, signed manifests, or llms.txt. Discovery is never authorization.
Authorize the exact Base Sepolia USDC quote. Underpayment and overpayment are rejected.
AgentPay forwards one signed request only after final payment and an atomic transaction claim.
Receipts, evidence, transaction state, and seller-reported refund records remain in the control plane.
Reference
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.
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.
Complete onboarding first; AgentPay reveals connector setup only after every server-authoritative prerequisite passes.