API

Payment & content API

The money path: the x402 payment gateway tells agents how to pay and settles payments on Stellar, and the hydration service returns the real content to anyone who has paid or proven they're human. Base URL https://api.verivyx.com. See the x402 flow guide for the narrative.

Endpoints at a glance

Payment gateway

Get payment requirements

GET /api/v1/payment/requirements?domain&slug — no auth. Returns the x402 PaymentRequired body and a PAYMENT-REQUIRED header (base64). Responds 402 when the paywall is on, 200 when off.

curl -i "https://api.verivyx.com/api/v1/payment/requirements?domain=example.com&slug=my-article"
# → 402 Payment Required
#   PAYMENT-REQUIRED: <base64 requirements>
#   { "x402Version": 2, "accepts": [ /* Soroban + classic USDC */ ], ... }

Quote a price

GET /api/v1/payment/quote?domain — no auth. Returns the price, atomic amount, asset, network, and destination for a domain.

Verify a payment

POST /api/v1/payment/verify — internal/service-to-service only. Requires theX-Internal-Token header (the shared secret configured via environment variable). External callers receive 401 Unauthorized. A dry run: validates a signed payment against the requirement without submitting it on-chain. Body is the x402 facilitator request.

# Internal service call — requires X-Internal-Token
curl https://api.verivyx.com/api/v1/payment/verify \
  -H 'Content-Type: application/json' \
  -H 'X-Internal-Token: <internal-token>' \
  -d '{
    "x402Version": 2,
    "paymentPayload": { "x402Version": 2, "accepted": { ... }, "payload": { "transaction": "<xdr>", "payer": "G…" } },
    "paymentRequirements": { ... }
  }'
# → { "isValid": true, "payer": "G…" }

Settle a payment

POST /api/v1/payment/settle — internal/service-to-service only. Requires theX-Internal-Token header. External callers receive 401 Unauthorized. Submits the signed payment on-chain, splits creator/platform, and opens a one-hour paid session for the (domain, slug). Pass an Idempotency-Key header to make retries safe — a repeat with the same key replays the cached result instead of charging again. The response also carries a PAYMENT-RESPONSE header.

# Internal service call — requires X-Internal-Token
curl https://api.verivyx.com/api/v1/payment/settle \
  -H 'Content-Type: application/json' \
  -H 'X-Internal-Token: <internal-token>' \
  -H 'Idempotency-Key: 0f3c…unique' \
  -d '{ "x402Version": 2, "paymentPayload": { … }, "paymentRequirements": { … } }'
# → { "success": true, "transaction": "…", "distributeTransaction": "…", "network": "stellar:testnet" }

Supported & health

GET /api/v1/payment/supported returns the facilitator's supported schemes/networks. GET /api/v1/payment/health is a liveness probe.

Content hydration

Hydrate content

POST /api/v1/content/hydrate with body { domain, slug }. Authorize with any of: an X-PAYMENT/PAYMENT-SIGNATURE header, an Authorization: Bearer human-session JWT, or an existing paid session from /payment/settle. On success the body includes served(passthrough, paid_agent, or human) and the article html.

# Agent that just settled retries the resource via hydrate:
curl https://api.verivyx.com/api/v1/content/hydrate \
  -H 'Content-Type: application/json' \
  -H 'PAYMENT-SIGNATURE: <signed x402 payload>' \
  -d '{ "domain": "example.com", "slug": "my-article" }'
# → 200 { "status": "success", "served": "paid_agent", "html": "<p>…</p>" }
# → 402 (with x402 requirements) when no valid auth is present