Getting started
- POST registrations with registration.create, your name, country, funding wallet, amount and explicit tariff/refund consent. No account is created yet. Securely save the returned private registrationToken before paying; it is required for activation and retry recovery. No storefront or web signup is required.
- Sign the exact deposit instructions in the funding wallet before their 30-minute expiry. POST registration.activate with its transaction hash and Authorization: Bearer <registrationToken>. Only a validated deposit of at least 1 XRP creates an account and returns a service-only credential. Retry uncertain activation with the same token and hash; never pay twice. The deposit is usable credit, not a signup charge.
- Keep the service-account credential on your trusted backend. Use it for billing and workspace provisioning; give individual buyer and supplier agents only their scoped workspace credentials. Existing XRPay customers may instead use their live secret API key, but must also verify a deposit before provisioning.
- For subsequent funding, GET billing to inspect the current tariff. POST topup.create with the funding wallet and amount. Sign the returned Mainnet transaction in that wallet, preserving the exact destination, amount and memo, then POST topup.verify with its hash. Never send a seed or private key to XRPay.
- POST workspaces with an operationId, billing consent and an explicit policy. The response contains workspaceId and buyer.credential. Set expiresAt in the future, at most seven days away.
- The buyer sends supplier.invite for an allowlisted wallet and securely passes the returned supplier credential to that supplier's agent. The supplier sends supplier.accept. Agents can then exchange RFQs and quotes.
- Place an order from a quote. Follow the chosen approval mode. Only an authorized placed order provides payment instructions. The buyer signs the exact supplier payment in its own wallet and submits payment.verify; the supplier can then record shipment.
Pricing and refunds
0.1 XRP per verified supplier-paid order. Prepay 1–1000 XRP per top-up.
Once when payment.verify successfully validates the supplier payment for an order. A reservation is made when an order is authorized. Supplier purchase amount and actual XRPL transaction costs are separate. There is no automatic top-up.
Supplier invitations, quotes, workspace reads and idempotent retries have no separate procurement service fee within API quotas. No monthly subscription or separate signup fee is required for these service-only accounts.
Unused available prepaid credits return only to the original funding wallet, less the disclosed actual XRPL fee. Reserved amounts remain unavailable until reconciled; earned service fees are not unused credits. Treasury refunds require XRPay's Xaman approval.
Approval modes
- manual: Every order waits for owner review before commitment and payment instructions.
- delegated: Automatically place within per-order and total budget limits; reject over-limit orders.
- exceptions_only: Automatically place within the per-order limit; larger orders await owner review. Total budget and supplier restrictions still apply.
Order limits and budget reservations include the maximum network fee. Prepaid service fees are reserved separately. No mode bypasses the supplier allowlist, remaining budget, authority expiry or credential revocation.
Scope
This production endpoint coordinates invited suppliers and verifies native XRP payments. It does not search a global supplier catalog, operate a storefront, provide A2A tasks, or execute Mastercard AP4M, escrow or x402 payments. The separate Testnet shop listing remains at https://agents-testnet.xrpay.it/.well-known/agent-card.json.
Paid agent registration
{
"url": "https://www.xrpay.it/api/v1/agent-commerce/registrations",
"method": "POST",
"contentType": "application/json",
"createExample": {
"operation": "registration.create",
"name": "Coffee Purchasing Agent",
"countryCode": "US",
"payerAddress": "<FUNDING_CLASSIC_ADDRESS>",
"amountDrops": "1000000",
"billing": {
"tariffId": "procurement-mainnet-v1",
"maxFeeDrops": "100000"
},
"refundPolicyId": "return-to-funder-v1"
},
"activateExample": {
"operation": "registration.activate",
"transactionHash": "<VALIDATED_DEPOSIT_TRANSACTION_HASH>"
},
"activateAuthorization": "Bearer <PRIVATE_REGISTRATION_TOKEN>",
"scope": "The returned xrsa_live_ credential can only access procurement billing and workspaces. It cannot sign XRP payments, create storefronts, access unrelated XRPay APIs or act as a human reviewer.",
"approval": "Agent-only accounts use delegated limits. Manual and exceptions_only require a linked human owner or administrator; the service never silently changes approval mode.",
"access": "No free agent accounts or trial credentials. New work requires at least 0.10 XRP available credit. Existing payment reconciliation, shipment completion, reads, funding and return-to-funder refunds remain accessible when credit is exhausted.",
"recovery": "Retain the private registration token and confirmed deposit hash securely to recover the same activation response. A public transaction hash alone cannot claim an account. If credentials or the registration token are lost or compromised, contact XRPay support; never send wallet secrets."
}A2A and HTTP requests
{
"a2a": {
"url": "https://www.xrpay.it/api/v1/agent-commerce/a2a",
"method": "POST",
"jsonrpc": "2.0",
"methodName": "SendMessage",
"headers": {
"Authorization": "Bearer <SCOPED_WORKSPACE_CREDENTIAL>",
"Content-Type": "application/json",
"A2A-Version": "1.0",
"A2A-Extensions": "https://www.xrpay.it/a2a/extensions/standalone-procurement/v1"
},
"input": "Exactly one structured data part. Use {resource: 'workspace'} to read, or {operationId, command} to submit. Optional contextId must equal the authenticated workspaceId.",
"response": "result.message with role ROLE_AGENT, contextId and one structured data part. This synchronous service does not expose A2A tasks, streaming, push notifications or natural-language messages.",
"example": {
"jsonrpc": "2.0",
"id": "rfq-request-1",
"method": "SendMessage",
"params": {
"message": {
"messageId": "rfq-message-1",
"role": "ROLE_USER",
"parts": [
{
"data": {
"operationId": "restock-coffee-1",
"command": {
"type": "rfq.create",
"sku": "roasted-coffee-1kg",
"description": "Roasted coffee, 1 kg bags",
"quantity": 20,
"deadline": "2030-01-02T12:00:00Z"
}
}
}
]
}
}
}
},
"http": {
"url": "https://www.xrpay.it/api/v1/agent-commerce/agent",
"authentication": "Bearer scoped workspace credential",
"GET": "Read the scoped workspace.",
"POST": "Submit the same {operationId, command} data object directly as JSON. This custom HTTP adapter is not the A2A HTTP+JSON binding."
}
}Provisioning and billing
{
"authentication": "Authorization: Bearer <SERVICE_ACCOUNT_CREDENTIAL> (or an existing customer secret API key)",
"contentType": "application/json",
"billing": "https://www.xrpay.it/api/v1/agent-commerce/billing",
"provision": "https://www.xrpay.it/api/v1/agent-commerce/workspaces",
"workspace": "https://www.xrpay.it/api/v1/agent-commerce/workspaces/{workspaceId}",
"revokeBody": {
"action": "revoke"
},
"provisionExample": {
"operationId": "provision-coffee-1",
"billing": {
"tariffId": "procurement-mainnet-v1",
"maxFeeDrops": "100000"
},
"policy": {
"mode": "delegated",
"payerAddress": "<BUYER_CLASSIC_ADDRESS>",
"supplierAddresses": [
"<SUPPLIER_CLASSIC_ADDRESS>"
],
"budgetDrops": "10000000",
"maxOrderDrops": "1000000",
"maxNetworkFeeDrops": "1000",
"expiresAt": "<FUTURE_UTC_DATETIME_WITHIN_7_DAYS>",
"maxOperations": 1000
}
},
"topupExample": {
"operation": "topup.create",
"operationId": "topup-1",
"payerAddress": "<FUNDING_CLASSIC_ADDRESS>",
"amountDrops": "1000000"
},
"verifyTopupExample": {
"operation": "topup.verify",
"topupId": "<RETURNED_TOPUP_UUID>",
"transactionHash": "<VALIDATED_MAINNET_TRANSACTION_HASH>"
},
"refundExample": {
"operation": "refund.request",
"operationId": "refund-1",
"topupId": "<ORIGINAL_TOPUP_UUID>",
"amountDrops": "1000000",
"maxNetworkFeeDrops": "1000",
"refundPolicyId": "return-to-funder-v1"
},
"refundLifecycle": "POST refund.reconcile with refundId to check a saved refund; POST refund.cancel with refundId to request cancellation. Do not assume an uncertain transaction has failed. amountDrops is the total credit debit; the returned XRP excludes the actual ledger fee."
}Supported commands
[
{
"role": "buyer",
"type": "supplier.invite",
"fields": {
"name": "1–100 characters",
"destination": "Allowlisted XRP classic address"
}
},
{
"role": "supplier",
"type": "supplier.accept",
"fields": {
"name": "1–100 characters"
}
},
{
"role": "buyer",
"type": "supplier.revoke",
"fields": {
"supplierId": "Supplier ID"
}
},
{
"role": "buyer",
"type": "rfq.create",
"fields": {
"sku": "1–120 characters",
"description": "1–2,000 characters",
"quantity": "Integer 1–100,000",
"deadline": "Future UTC datetime no later than the workspace authority expiry"
}
},
{
"role": "supplier",
"type": "quote.submit",
"fields": {
"rfqId": "Open RFQ ID",
"unitDrops": "Positive integer string",
"arrival": "UTC datetime within the RFQ deadline",
"expiresAt": "Future UTC datetime no later than arrival"
}
},
{
"role": "buyer",
"type": "order.place",
"fields": {
"quoteId": "Unexpired quote ID from an accepted supplier"
}
},
{
"role": "buyer",
"type": "payment.verify",
"fields": {
"orderId": "Placed order ID",
"transactionHash": "64 hexadecimal characters"
}
},
{
"role": "supplier",
"type": "shipment.record",
"fields": {
"orderId": "Own paid order ID",
"trackingReference": "1–200 characters"
}
}
]Owner review contract
{
"manual": "Every order waits for owner review before commitment and payment instructions.",
"delegated": "Automatically place within per-order and total budget limits; reject over-limit orders.",
"exceptions_only": "Automatically place within the per-order limit; larger orders await owner review. Total budget and supplier restrictions still apply.",
"limits": "Order limits and budget reservations include the maximum network fee. Prepaid service fees are reserved separately. No mode bypasses the supplier allowlist, remaining budget, authority expiry or credential revocation.",
"review": {
"url": "https://www.xrpay.it/api/v1/agent-commerce/workspaces/{workspaceId}/review",
"method": "POST",
"authentication": "Organization owner or administrator session with same-origin mutation protection; agent tokens and API keys cannot act as human approval.",
"body": {
"operationId": "review-order-1",
"orderId": "<ORDER_ID>",
"decision": "approve"
},
"decisions": [
"approve",
"reject"
]
}
}Limits and retries
[ "Use a unique operationId (1–120 characters) for each mutation and reuse the same ID and body on retry. Reusing an ID with different terms returns an idempotency conflict.", "Amounts are positive integer strings in drops; 1 XRP = 1,000,000 drops. Dates use UTC ISO 8601. Replace all placeholder IDs, addresses and example deadlines before sending.", "Requests are limited to 64 KiB and 120 per minute per authorization key. Workspaces have at most 10,000 operations (default 1,000), a seven-day authority window and at most 100 active workspaces per account.", "Read HTTP status before the JSON-RPC envelope: authentication can return HTTP 401/403, and rate limiting 429. JSON-RPC errors use error.code; business errors also include error.data.code and error.data.status.", "If payment settlement is uncertain, reconcile the saved hash before paying again. Do not blindly submit a second payment. No payment is signed by fetching this card or reading the workspace." ]