Endpoints

The resource server calls these endpoints; the buyer never calls the Facilitator directly. On mainnet /supported, /verify and /settle carry Authorization: Bearer <API_KEY>; /health is open. Payment bodies follow the x402 v2 specification.

Service

Status and advertised capabilities.

GET/healthLiveness and build info

Request

No parameters.

Response 200

okboolean

True while the service is serving.

servicestring

Service identifier, agentsmith-stellar-facilitator.

versionstring

Deployed build version.

networkstring

CAIP-2 network the deployment serves, stellar:testnet or stellar:pubnet.

GET/supportedAdvertised payment capabilities

Request

No parameters.

Response 200

kindsarray

The payment kinds this deployment accepts.

x402Versioninteger

Protocol version. 2.

schemestring

exact, or upto when a Kernel is configured.

networkstring

CAIP-2 network the kind applies to.

extraobjectoptional

Scheme metadata, including areFeesSponsored.

extensionsstring[]

Enabled protocol extensions.

signersobject

CAIP-2 network pattern mapped to the deployment's public signer addresses.

Payments

Verify and settle a buyer's signed payment. Both take the same x402 v2 body.

POST/verifyValidate a payment, no funds moved

Request body

x402Versionintegerrequired

Protocol version. 2.

paymentPayloadobjectrequired

The buyer's signed payment.

x402Versioninteger

2; must match the top-level version.

acceptedobject

The payment requirements the buyer accepted (same shape as below).

payloadobject

Scheme-specific signed authorization.

resourceobjectoptional

Resource metadata passed through from the challenge.

extensionsobjectoptional

x402 extension data.

paymentRequirementsobjectrequired

The terms the payment is validated against.

schemestring

exact or upto.

networkstring

CAIP-2 network, e.g. stellar:testnet.

amountstring

Atomic units as a digit string.

assetstring

SEP-41 token contract.

payTostring

Recipient Stellar address.

maxTimeoutSecondsinteger

Authorization lifetime, 1–300.

extraobjectoptional

Scheme metadata, e.g. the upto settlement contract.

Response 200

isValidboolean

Whether the payment would settle.

payerstringoptional

Buyer address recovered from the signature.

invalidReasonstringoptional

Machine-readable code when isValid is false.

invalidMessagestringoptional

Human-readable detail for the failure.

POST/settleSubmit and confirm a payment

Request body

Same body as POST /verify: x402Version, paymentPayload and paymentRequirements. Idempotent in the Buyer's signed payment — resending the same payment resolves a timeout or uncertain answer without a second settlement. See Retries and idempotency.

Response 200

successboolean

Whether settlement is confirmed.

transactionstring

Stellar transaction hash; empty when nothing was submitted.

networkstring

CAIP-2 network the payment settled on.

payerstringoptional

Buyer address.

amountstringoptional

Settled amount in atomic units.

errorReasonstringoptional

Machine-readable code when settlement did not succeed. Besides the x402 reasons, the Facilitator uses the local extensions settlement_pending (broadcast but not yet confirmed — resend to reconcile), settlement_expired (the authorization window closed before confirmation) and settlement_conflict (a resend whose caller or terms differ from the original).

errorMessagestringoptional

Human-readable detail for the failure.

Internal

Served only on the private internal listeners, never on the public port, and never by a resource server. See Self-hosting.

GET/internal/discovery/usagePer-resource usage for Bazaar reporting

Request

No API key; reachable only on the internal usage port.

cursorstringoptional

A catalog key (64 lower-case hex) to page after; the page starts strictly after it.

limitintegeroptional

Page size, 1–10000. Default 10000.

Response 200

itemsarray

Per-catalog-key usage over the last 30 days.

catalogKeystring

Catalog key, 64 lower-case hex.

totalCalls30dinteger

Settlements for the key in the last 30 days.

uniquePayers30dinteger

Distinct payer addresses in the last 30 days.

nextCursorstringoptional

Catalog key to pass as the next cursor, or null on the last page.

Key management is a gRPC Credentials service on its own private port; it has no HTTP route. Every call carries the shared token as authorization: Bearer <token> metadata, or gets UNAUTHENTICATED. On the hosted service the AgentSmith platform calls it; a self-hoster calls it on their own network. Field names below are the proto's.

RPCCredentials.RegisterCreate a Resource Server and its first key

Request

namestringrequired

Display name.

domainstringrequired

A bare host name; stored lower-case without a trailing dot.

emailstringrequired

Contact email.

Response

resource_server_idstring

The new Resource Server's id.

credential_idstring

The first key's id.

api_keystring

The plaintext key, returned only here.

Errors

ALREADY_EXISTS (DOMAIN_TAKEN) when an active server holds the domain; INVALID_REQUEST.

RPCCredentials.IssueKeyIssue a new current key

Request

resource_server_idstringrequired

The Resource Server to issue for.

Response

credential_idstring

The new key's id.

api_keystring

The plaintext key, returned only here. The previous current key keeps working for ten minutes.

Errors

NOT_FOUND; FAILED_PRECONDITION (SERVER_DISABLED).

RPCCredentials.RevokeKeyRevoke a key immediately

Request

credential_idstringrequired

The key to revoke.

Response

Empty. Revoking an already-revoked key succeeds again.

Errors

NOT_FOUND.