Sandbox bootstrap queued The seeded demo agents are being prepared in the background. The auth picker will hydrate automatically when they are ready.
1STEP 1 · IN PROGRESS
Register
Create a sandbox agent identity
2STEP 2
Select
Choose the sandbox agent for this browser
3STEP 3
Fund
Load sandbox wallet · +$1,000
4STEP 4
Pay
Move money between agents
5STEP 5
Inspect
Review ledger + receipts
Agents
Wallets
Payments
Policies
Analytics
Webhooks
Services
Disputes
Payouts
Operators
x402 Protocol
AP2 Protocol
A2A Protocol
Host browser 0 sandbox identities No agent selected
1STEP 1 · IN PROGRESS
Register
Create a sandbox agent identity
2STEP 2
Select
Choose the sandbox agent for this browser
3STEP 3
Fund
Load sandbox wallet · +$1,000
4STEP 4
Pay
Move money between agents
5STEP 5
Inspect
Review ledger + receipts
POST /v1/agents
Register Agent
Create a new AI agent identity. Returns an Ed25519 key pair, a unique API key, and an empty hot wallet. Store secret_key securely — it is returned only once.
No Auth Required Idempotent via X-Request-ID Rate 30 Req/Min Scope Write:Agents
Docs ↗
FieldTypeRequiredDescription
namestringRequiredHuman-readable agent name. Max 255 chars, unique per operator.
operatorstringOptionalOperator identifier. Defaults to "self".
metadataobjectOptionalArbitrary JSON metadata (indexed, max 16KB).
Will appear in receipts and webhooks.
Used for multi-tenant scoping.
This browser flow adds one custom agent to the sandbox. Use the seeded agents for the rest of the demo path.
Send a request to see the response here.
shell 
curl -X POST https://agentpayement.com/v1/agents 
  -H "Content-Type: application/json" 
  -H "X-Request-Id: $(uuidgen)" 
  -d '{"name":"MyBot","operator":"acme-corp"}'
GET /v1/agents/:id Auth required
Get Agent
Fetch an agent's profile, trust score, status, and wallet references.
ParamTypeRequiredDescription
iduuid (path)requiredAgent UUID
GET /v1/wallets Auth required
List Wallets
Returns all wallets belonging to the authenticated agent, including balance and type.
No parameters needed — uses the Authorization bearer token to scope results.
GET /v1/wallets/:id/balance Auth required
Wallet Balance
Fetch the current balance and type for a specific wallet. Only accessible by the owning agent.
ParamTypeRequiredDescription
iduuid (path)requiredWallet UUID
POST /v1/wallets/:id/fund Auth required
Fund Wallet
Add funds to a wallet from a test faucet or external source. Only the owning agent can fund their own wallets.
FieldTypeRequiredDescription
iduuid (path)requiredWallet UUID to fund
amountnumberrequiredUSD amount to add (max 1,000,000)
sourcestringoptionalOne of: test_faucet, bank_transfer, crypto (default: test_faucet)
POST /v1/payments Auth required
Create Payment
Execute a payment from a payer wallet. The full 7-step pipeline runs: validation → idempotency check → ownership → fee calc → balance check → policy evaluation → atomic DB transaction → webhook dispatch.
FieldTypeRequiredDescription
from_wallet_iduuidrequiredPayer wallet UUID (must belong to auth agent)
to_wallet_iduuidone ofRecipient internal wallet UUID
to_externalstringone ofExternal recipient address (for ACH, card, crypto). Either to_wallet_id or to_external is required.
amountnumberrequiredUSD amount (positive)
railstringoptionalinternal · x402 · ach · card · crypto (default: internal)
descriptionstringoptionalPayment description (max 500)
idempotency_keystringoptionalUnique key for retry safety (max 255)
For internal rail set To Wallet ID. For ach / card / crypto set External Recipient instead.
GET /v1/payments/:id Auth required
Get Payment
Look up a transaction by ID. Returns full transaction record including policy evaluation results.
ParamTypeRequiredDescription
iduuid (path)requiredTransaction UUID (returned from POST /v1/payments)
POST /v1/payments/:id/refund Auth required
Refund Payment
Reverse a completed transaction. Returns the full debited amount (including fee) to the payer wallet. Only the paying agent can initiate a refund.
ParamTypeRequiredDescription
iduuid (path)requiredTransaction UUID to refund
GET /v1/policies Auth required
List Policies
Returns all active and inactive policies attached to the authenticated agent. Policies are evaluated in priority order before every payment.
No parameters needed. Results scoped to the authenticated agent.
POST /v1/policies Auth required
Create Policy
Add a spend-control policy for the authenticated agent. Policies run before every payment and can block or flag transactions.
FieldTypeRequiredDescription
policy_typestringrequiredspend_limit · velocity · allowlist · blocklist · time_restriction · approval
rulesobjectrequiredPolicy-type specific rule object (see examples)
priorityintegeroptionalEvaluation order 0–100, higher = evaluated first (default: 0)
spend_limit: {"max_amount": 500, "period": "daily"}
velocity: {"max_transactions": 10, "window_minutes": 60}
blocklist: {"blocked_wallets": ["uuid1","uuid2"]}
allowlist: {"allowed_wallets": ["uuid1"]}
GET /v1/analytics/spend Auth required
Spend Analytics
Aggregated spend breakdown by rail for the authenticated agent over the given time window. Returns totals and per-rail counts, volumes, and fees.
ParamTypeRequiredDescription
daysinteger (query)optionalLookback window in days, 1–90 (default: 30)
GET /v1/webhooks Auth required
List Webhooks
Returns all webhook registrations for the authenticated agent.
No parameters needed.
POST /v1/webhooks Auth required
Register Webhook
Register a URL to receive signed event payloads. Returns a secret — use it to verify HMAC signatures on incoming events.
FieldTypeRequiredDescription
urlstring (uri)requiredHTTPS endpoint that will receive events
eventsarrayoptionalEvent filter list. Use ["*"] for all events, or specify: payment.completed · payment.failed · payment.refunded · policy.violated
DELETE /v1/webhooks/:id Auth required
Delete Webhook
Permanently remove a webhook registration. Events will no longer be sent to the associated URL.
ParamTypeRequiredDescription
iduuid (path)requiredWebhook UUID (from GET /v1/webhooks)
GET /v1/webhooks/events Auth required
Recent Webhook Events
Returns in-memory log of recently dispatched webhook events for the authenticated agent. Useful for debugging delivery.
ParamTypeRequiredDescription
limitinteger (query)optionalMax events to return (default: 50)
POST /v1/operators
Register Operator
Create a new operator account. Returns a one-time api_key (prefix op_live_…). Store it securely — it is returned only once. Use this key in the Authorization: Bearer <op_live_…> header when registering services or managing API keys.
No Auth Required Rate 5 Req/Hour
FieldTypeRequiredDescription
namestringRequiredDisplay name for the operator. Max 255 chars.
Identifies your organization in logs and receipts.
Send a request to see the response here.
shell 
curl -X POST https://agentpayement.com/v1/operators 
  -H "Content-Type: application/json" 
  -d '{"name":"Acme Corp"}'
GET /v1/operators/api-keys Operator Auth required
List Operator API Keys
Returns all active API keys for the authenticated operator.
The op_live_… key returned when you registered your operator.
POST /v1/operators/api-keys Operator Auth required
Create Operator API Key
Issue an additional API key for the authenticated operator. Useful for rotating credentials or scoping keys per service.
The op_live_… key returned when you registered your operator.
Optional human-readable label for this key.
POST /v1/x402/pay Auth required
x402 HTTP Payment
Process an HTTP 402 Payment Required flow. The agent pays for access to a resource URL using the x402 protocol. Returns a receipt and retry headers to attach to the original request.
FieldTypeRequiredDescription
target_urlstring (uri)requiredURL of the resource that returned HTTP 402
wallet_iduuidrequiredPayer wallet UUID
amountnumberrequiredAmount requested by the paywall
currencystringoptionalUSD or USDC (default: USD)
payee_addressstringoptionalPayee identifier from the X-Payment-Address header
max_amountnumberoptionalAgent's spending cap for this resource (request rejected if amount exceeds this)
Use GET /v1/x402/paywall/:resource first to get a 402 response, then use those payment details here.
GET /v1/x402/paywall/:resource No auth required
Paywall Check
Probe a paywalled resource. Always returns HTTP 402 with payment requirements in body and headers. Use the returned amount and payee to construct a payment via POST /v1/x402/pay.
ParamTypeRequiredDescription
resourcestring (path)requiredResource path slug (e.g. api/premium-data)
pricenumber (query)optionalOverride price in USD (default: 0.01)
POST /v1/ap2/mandates Auth required
Issue AP2 Mandate
Issue a cryptographically signed Verifiable Digital Credential (VDC) per the AP2 spec. AgentPay acts as the Credentials Provider and signs the mandate envelope with an Ed25519 key — any party can verify authenticity without trusting the transport.

intent — pre-authorises an agent to spend autonomously up to max_amount (human-not-present).
cart — authorises a specific purchase; redeemable once via /redeem (human-present).
payment — signals agent involvement to the payment ecosystem for fraud/risk scoring.
FieldTypeRequiredDescription
mandate_typestringrequiredintent | cart | payment
payloadobjectrequiredMandate-specific data (see templates below)
ttl_secondsintegeroptionalTime-to-live in seconds (default: 3600)
Switch mandate_type to load a template payload. intent mandates enforce a spending ceiling; cart mandates can be redeemed with the returned mandate_id.
GET /v1/ap2/mandates Auth required
List Mandates
List all AP2 mandates issued by the authenticated agent, with optional filtering by type and status.
FieldTypeRequiredDescription
typestring (query)optionalFilter by mandate_type: intent | cart | payment
statusstring (query)optionalFilter by status: active | redeemed | expired | revoked
limitinteger (query)optionalMax records to return (default: 20, max: 100)
GET /v1/ap2/mandates/:id No auth required
Get + Verify Mandate
Retrieve a mandate by ID and verify its Ed25519 signature. This endpoint is public — merchants and verifiers can check mandate authenticity without an AgentPay account. The response includes signature_valid: true/false and the credentials_provider_public_key for independent verification.
POST /v1/ap2/mandates/:id/redeem Auth required
Redeem Cart Mandate
Redeem a cart mandate — this atomically triggers a payment using the payer/payee details embedded in the mandate. Only redeemable once; subsequent calls return 409. All payment fields default to values in the mandate payload; use the override fields below only to fill gaps.
FieldTypeRequiredDescription
id (path)stringrequiredMandate ID from issue response
wallet_idstring (body)optionalOverride payer wallet (defaults to mandate payload)
amountnumber (body)optionalOverride amount (must not exceed mandate ceiling)
POST /v1/ap2/mandates/:id/revoke Auth required
Revoke Mandate
Revoke an active mandate before it expires or is redeemed. Once revoked the mandate cannot be redeemed and any verifier checking it will see status: revoked. Use this when user consent is withdrawn or a purchase is cancelled.
GET /a2a/agentpay No auth required
Agent Card
Returns the AgentPay A2A Agent Card — the AP2 discovery document. Any A2A-compatible agent fetches this to confirm AP2 support, learn the endpoint URL, and retrieve the credentials provider public key for mandate verification.
No parameters. Public endpoint — no API key needed.
POST /a2a/agentpay Auth required
A2A — Issue IntentMandate
Issues a cryptographically signed credential granting the agent pre-authorization to spend within the stated bounds — human-not-present scenario. The credential is verifiable by any third party using the AgentPay public key.
POST /a2a/agentpay Auth required
A2A — Accept CartMandate
Submit a merchant's cart using the W3C Payment Request API format. AgentPay validates the cart, issues a signed credential, and returns the agent's eligible wallet-based payment methods — human-present scenario.
POST /a2a/agentpay Auth required
A2A — Record PaymentMandate
Records a payment signal credential linking user authorization, merchant, and chosen payment method. Payment networks use this for agent-awareness and risk scoring. Use POST /v1/payments separately to move funds.
GET /v1/services Public
Discover Services
Browse the service marketplace. Filter by category or verified status. Returns reputation scores, SLA terms, pricing, and the endpoint URL for each service.
ParamTypeRequiredDescription
categorystring (query)optionalgeneral · search · ml · data · compute · storage · communication · finance · other
verifiedboolean (query)optionaltrue = verified services only
limitinteger (query)optionalMax results (default 50, max 100)
GET /v1/services/:id Public
Get Service
Fetch full details for a service by ID, including pricing, SLA terms, input/output schemas, and reputation stats.
ParamTypeRequiredDescription
iduuid (path)requiredService UUID
GET /v1/services/:id/stats Public
Service Reputation Stats
Live reputation metrics for a service: success rate, SLA compliance, p50/p95 latency, dispute rate, and weighted confidence score. Recalculated after each settlement.
ParamTypeRequiredDescription
iduuid (path)requiredService UUID
POST /v1/services/:id/authorize Auth required
Authorize Service Payment
Agent A pre-authorizes payment for a service. Debits the wallet and issues a short-lived token (15 min TTL). Pass the token to Agent B in the X-AgentPay-Token header. Agent B redeems it via POST /v1/x402/verify.
Scope tokens:issue
FieldTypeRequiredDescription
iduuid (path)requiredService UUID to authorize
from_wallet_iduuidrequiredPayer wallet — must have sufficient balance
request_bindingobjectoptionalArbitrary binding data included in the token (tied to this specific call)
POST /v1/services Operator Auth
Register Service
List a new AI service in the marketplace. Requires operator authentication and an active agent to attach the service to. Returns a service ID used for payments and discovery.
Scope services:write
FieldTypeRequiredDescription
agent_iduuidrequiredAgent that will provide this service
namestringrequiredDisplay name (max 255 chars)
endpoint_urlurirequiredHTTPS URL where Agent A sends requests
pricing.per_callnumberrequiredFee per API call in USD
categorystringoptionalgeneral · search · ml · data · compute · storage · communication · finance · other
sla_timeout_msintegeroptionalSLA window in ms before auto-refund (default 30000)
POST /v1/disputes Auth required
Open Dispute
Open a dispute against a completed or authorized transaction where you are the payer. Only one active dispute per transaction allowed. Include evidence to help the review.
Scope disputes:write
FieldTypeRequiredDescription
transaction_iduuidrequiredTransaction to dispute (you must be the payer)
reasonstringrequiredservice_not_delivered · partial_delivery · quality_issue · sla_breach · unauthorized_charge · other
detailsstringoptionalHuman-readable description (max 2000 chars)
requested_refund_amountnumberoptionalAmount to refund (defaults to full principal)
evidenceobjectoptionalSupporting evidence JSON
GET /v1/disputes Auth required
List Disputes
List disputes for the authenticated agent. Use role=respondent to see disputes where you are the provider, or role=both for all.
ParamTypeRequiredDescription
rolestring (query)optionalcomplainant (default) · respondent · both
statusstring (query)optionalopen · under_review · resolved_refunded · resolved_denied · withdrawn
limitinteger (query)optionalMax results (default 50)
GET /v1/disputes/:id Auth required
Get Dispute
Fetch a dispute by ID, including the full event timeline. Only visible to the complainant or respondent.
POST /v1/disputes/:id/evidence Auth required
Submit Evidence
Submit supporting evidence to an open or under-review dispute. Both the complainant and respondent can submit. Submitting evidence moves the dispute to under_review if still open.
FieldTypeRequiredDescription
iduuid (path)requiredDispute UUID
evidenceobjectrequiredEvidence payload (URLs, logs, screenshots, etc.)
notesstringoptionalAccompanying text (max 2000 chars)
POST /v1/disputes/:id/withdraw Auth required
Withdraw Dispute
Withdraw your own open or under-review dispute. Only the complainant can withdraw. Once withdrawn, the dispute cannot be reopened.
POST /v1/payouts Auth required
Request Payout
Withdraw funds from an agent wallet to an external bank account, crypto address, or Stripe connected account. Requires a settlement provider to be configured — otherwise the request is saved with status pending_provider and processed once a provider is connected.
Scope payouts:write
FieldTypeRequiredDescription
wallet_iduuidrequiredSource wallet
amountnumberrequiredAmount to withdraw
destination.typestringrequiredbank · crypto · stripe
GET /v1/payouts Auth required
List Payouts
List all payout requests for the authenticated agent. Includes status, amount, destination type, and settlement timestamps.
ParamTypeRequiredDescription
statusstring (query)optionalpending · pending_provider · completed · failed · cancelled
limitinteger (query)optionalMax results (default 50)
DELETE /v1/payouts/:id Auth required
Cancel Payout
Cancel a payout that is still in pending or pending_provider status. Funds are returned to the wallet.
POST /v1/x402/verify Auth required
Verify & Settle Token
Agent B redeems a payment token received from Agent A via the X-AgentPay-Token header. Settles the pre-authorized payment atomically — credits Agent B's wallet. Idempotent: reuse the same token to check status without re-settling.
Scope tokens:redeem
FieldTypeRequiredDescription
tokenstringrequiredToken string from the X-AgentPay-Token header
request_bindingobjectoptionalMust match binding supplied by Agent A during authorize
POST /v1/x402/tokens/:id/call-started Auth required
Mark Call Started (SLA Clock)
Agent A calls this immediately after dispatching a request to Agent B. Starts the SLA clock. If Agent B does not redeem the token within the service's sla_timeout_ms, AgentPay automatically refunds Agent A in full (principal + fee).
Scope tokens:manage
POST /v1/x402/tokens/:id/accepted Auth required
Mark Provider Accepted
Agent B signals that it received and accepted Agent A's request. Records provider_accepted_at and ensures the SLA deadline is set.
Scope tokens:redeem
POST /v1/x402/tokens/:id/completed Auth required
Mark Provider Completed
Agent B signals it has fulfilled the service request. Optionally submits a completion proof object (e.g. hash of output, signed receipt). Records provider_completed_at.
Scope tokens:redeem
FieldTypeRequiredDescription
proofobject (body)optionalCompletion proof — any JSON object (hash, signature, output reference)
DELETE /v1/x402/tokens/:id/cancel Auth required
Cancel Token
Agent A cancels an unused issued token before it is redeemed or expires. Refunds the pre-authorized amount back to the payer wallet.
Scope tokens:manage
GET /v1/x402/requirements/:serviceId Public
x402 Payment Requirements
Protocol-native 402 discovery for any HTTP client. Returns the full payment flow instructions, pricing, and SLA terms for a service. Returns HTTP 402 with WWW-Authenticate and X-Payment-Required headers — any client can self-serve the payment flow.