TXRISK Docs | Action Authorization and x402 Quickstart

Buyer Path

Run the Lane 1 evaluator

Need the partner-review version?

Open /partner-evaluator.html for the listing-friendly bundle that includes review order, discovery metadata, MCP metadata, and the same live proof links.

Need the buyer-safe paid-success proof?

Open /action-authorization-paid-success.html for one stable public URL with the direct Base recovery sequence and a final paid 200 JSON body for POST /v1/action/authorize.

Need the buyer-safe response explainer?

Open /action-authorization-response-fields.html for a field-by-field read of decision, policy.reasons, operator.step, and billing, plus one shipped allow example and one shipped review example.

Open /playground.html and choose POST /v1/action/authorize.
Pick one policy template: treasury transfer, vendor payout, subscription purchase, or browser checkout.
Leave API key blank and run once so the browser performs the native x402 402 -> PAYMENT-SIGNATURE retry.
Confirm the final body includes decision, policy.reasons, operator.step, and billing.

export API_BASE_URL=""
export X_CHAIN="base"   # switch to tempo for Tempo mainnet

payload='{
  "action": {
    "kind": "approval",
    "chain": "base",
    "actor": "0x1111111111111111111111111111111111111111",
    "tokenAddress": "0x3333333333333333333333333333333333333333",
    "spender": "0x2222222222222222222222222222222222222222",
    "amountUsd": 299,
    "allowanceUsd": 299,
    "approvalScope": "exact"
  },
  "requestContext": {
    "intentId": "intent_subscription_purchase",
    "merchantAccountId": "merchant_subscription"
  }
}'

payment_required=$(curl -isS -X POST "$API_BASE_URL/v1/action/authorize" \
  -H "content-type: application/json" \
  -H "x-chain: $X_CHAIN" \
  -d "$payload" | tr -d '\r' | awk -F': ' '/^payment-required: / {print $2}')

payment_signature=$(printf '%s' "$payment_required" | base64 --decode | jq -r '.accepts[0].extra.txrisk.paymentPayload | @base64')

curl -sS -X POST "$API_BASE_URL/v1/action/authorize" \
  -H "content-type: application/json" \
  -H "x-chain: $X_CHAIN" \
  -H "payment-signature: $payment_signature" \
  -d "$payload" | jq

curl -sS "$API_BASE_URL/discovery/resources" | jq '.items[] | select(.resource=="/v1/action/authorize")'

Policy Templates

Four buyer-safe actions with deterministic outcomes

Treasury transfer

Use this to show a hard stop before a risky outbound treasury send is submitted.

Action: transfer
Expected decision: deny
Operator step: deny_and_rewrite_action

Vendor payout

Use this to show a clean pass on a low-risk vendor payment.

Action: transfer
Expected decision: allow
Operator step: proceed_to_submit

Subscription purchase

Use this to show a policy review gate on an approval-backed SaaS spend.

Action: approval
Expected decision: review
Operator step: require_operator_review

Browser checkout

Use this to show a bounded browser-agent approval that can pass automatically.

Action: approval
Expected decision: allow
Operator step: proceed_to_submit

API Catalog

Paid endpoints

POST /v1/wallet/risk-snapshot

Inputs: walletAddress, chainId, optional exposure/signal window.
Output: riskScore, riskBand, watch flags, billing block.
Usage price: 0.0020 USDC per admitted call.

POST /v1/webhook/verify

Inputs: tenant id, provider, endpoint id, event id, timestamp, raw body string, signature.
Output: verified/replay/signature metadata plus billing state.
Usage price: 0.0020 USDC per admitted call.

POST /v1/lead/qualify

Inputs: lead profile and ICP arrays for industries/pain points.
Output: fit score, tier, disqualify reasons, outreach angles, billing block.
Usage price: 0.0020 USDC per admitted call.

POST /v1/action/authorize

Inputs: transfer or approval action plus optional request context.
Output: allow/review/deny decision, policy reasons, operator next step, billing block.
Usage price: 0.0020 USDC per admitted call.

JSON Examples

Request + response samples

# POST /v1/wallet/risk-snapshot
# Use it when: you need a fast risk check before approving a wallet-linked action.
{
  "walletAddress": "PAYEE_ADDRESS",
  "chainId": 8453,
  "exposureUsd": 15000.25,
  "signalWindowHours": 24
}

# response
{
  "walletAddress": "PAYEE_ADDRESS",
  "chainId": 8453,
  "riskScore": 42,
  "riskBand": "medium",
  "topDrivers": [{"code": "volume_spike", "impact": 0.27}],
  "watchFlags": ["new_wallet"],
  "traceId": "risk_123456789abc",
  "billing": {"charged_usdc": "0.0020", "remaining_balance_usdc": "9.9980"}
}

# POST /v1/webhook/verify
# Use it when: you need TXRISK to resolve the signing secret server-side and block spoofed or replayed events.
{
  "tenantId": "tenant_demo",
  "provider": "stripe",
  "endpointId": "payments-primary",
  "eventId": "evt_123",
  "timestamp": "2026-03-25T00:00:00Z",
  "body": "{\"event\":\"invoice.paid\",\"id\":\"evt_123\"}",
  "signature": "sha256="
}

# response
{
  "tenantId": "tenant_demo",
  "provider": "stripe",
  "endpointId": "payments-primary",
  "eventId": "evt_123",
  "verified": true,
  "replayDetected": false,
  "signatureValid": true,
  "signatureScheme": "stripe-hmac-sha256",
  "policyAction": "allow",
  "verificationId": "whv_123456789abc",
  "billing": {"charged_usdc": "0.0020", "remaining_balance_usdc": "9.9960"}
}

# POST /v1/lead/qualify
# Use it when: you want to rank inbound leads and prioritize high-fit outreach quickly.
{
  "lead": {
    "company": "Acme Treasury",
    "domain": "acmetreasury.com",
    "industry": "fintech",
    "painPoints": ["manual_risk_reviews", "chargebacks"]
  },
  "icp": {
    "industries": ["fintech", "defi"],
    "mustHavePainPoints": ["manual_risk_reviews"]
  }
}

# response
{
  "company": "Acme Treasury",
  "fitScore": 81,
  "tier": "a",
  "matchedSignals": {"industryMatch": true, "painPointMatches": 1, "painPointTotal": 1},
  "disqualifyReasons": [],
  "outreachAngles": ["manual review automation", "chargeback prevention"],
  "qualificationId": "ldq_123456789abc",
  "billing": {"charged_usdc": "0.0020", "remaining_balance_usdc": "9.9940"}
}

# POST /v1/action/authorize
# Use it when: you need a paid policy gate before a treasury send, vendor payout, subscription purchase, or browser checkout executes.
{
  "action": {
    "kind": "approval",
    "chain": "base",
    "actor": "0x1111111111111111111111111111111111111111",
    "tokenAddress": "0x3333333333333333333333333333333333333333",
    "spender": "0x2222222222222222222222222222222222222222",
    "amountUsd": 299,
    "allowanceUsd": 299,
    "approvalScope": "exact"
  },
  "requestContext": {
    "intentId": "intent_subscription_purchase",
    "merchantAccountId": "merchant_subscription"
  }
}

# response
{
  "mode": "action_authorize",
  "authorizationId": "auth_123456789abc",
  "decision": "review",
  "policy": {"profile": "operator_guard_v1"},
  "operator": {"step": "require_operator_review"},
  "billing": {"charged_usdc": "0.0020", "remaining_balance_usdc": "0.0000"}
}

More Examples

Webhook, lead, and authorization curl

timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
body='{"event":"invoice.paid","id":"evt_123"}'
tenant_id='tenant_demo'
endpoint_id='payments-primary'
sig='sha256='

curl -sS -X POST "$API_BASE_URL/v1/webhook/verify" \
  -H "content-type: application/json" \
  -H "x-api-key: $X_API_KEY" \
  -d "{\"tenantId\":\"$tenant_id\",\"provider\":\"stripe\",\"endpointId\":\"$endpoint_id\",\"eventId\":\"evt_123\",\"timestamp\":\"$timestamp\",\"body\":$body,\"signature\":\"$sig\"}" | jq

curl -sS -X POST "$API_BASE_URL/v1/lead/qualify" \
  -H "content-type: application/json" \
  -H "x-api-key: $X_API_KEY" \
  -d '{
    "lead": {
      "company": "Acme Treasury",
      "domain": "acmetreasury.com",
      "industry": "fintech",
      "painPoints": ["manual_risk_reviews", "chargebacks"]
    },
    "icp": {
      "industries": ["fintech", "defi"],
      "mustHavePainPoints": ["manual_risk_reviews"]
    }
  }' | jq

payload='{
  "action": {
    "kind": "approval",
    "chain": "base",
    "actor": "0x1111111111111111111111111111111111111111",
    "tokenAddress": "0x3333333333333333333333333333333333333333",
    "spender": "0x222222222222222222222222222222222222222c",
    "amountUsd": 2500,
    "allowanceUsd": 25000,
    "approvalScope": "unlimited"
  },
  "requestContext": {
    "intentId": "intent_x402_recovery"
  }
}'

payment_required=$(curl -isS -X POST "$API_BASE_URL/v1/action/authorize" \
  -H "content-type: application/json" \
  -H "x-chain: $X_CHAIN" \
  -d "$payload" | tr -d '\r' | awk -F': ' '/^payment-required: / {print $2}')

payment_signature=$(printf '%s' "$payment_required" | base64 --decode | jq -r '.accepts[0].extra.txrisk.paymentPayload | @base64')

curl -sS -X POST "$API_BASE_URL/v1/action/authorize" \
  -H "content-type: application/json" \
  -H "x-chain: $X_CHAIN" \
  -H "payment-signature: $payment_signature" \
  -d "$payload" | jq

Auth + Billing

Headers, payment behavior, and recovery

Public sellable routes use PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE.
The same sellable routes also accept x-api-key as a fallback test harness path; current quickstart still leads with the native x402 flow.
Optional routing/trace headers: x-request-id, x-chain (base default, tempo optional).
x-api-key remains the fallback/test harness path for the sellable routes and is still required for internal-only routes such as /v1/wallet/risk-quickstart, /v1/bankr/preflight, and operator support surfaces.
No bridging is required or supported in this flow. Calls are paid and executed directly on the selected rail (base or tempo).
For wallet risk snapshot, keep body chainId aligned with selected route (base: 8453, tempo: 4217).
Public 402 payment_required responses include machine-readable x402 metadata in both the body and the PAYMENT-REQUIRED header.
Successful paid responses include billing.charged_usdc plus a PAYMENT-RESPONSE settlement artifact.

Remote MCP

Use TXRISK from Claude/Codex-style connectors

Remote MCP endpoint: POST /mcp.
Metadata helper: GET /.well-known/mcp/server.json.
The wrapper is intentionally bounded to five read-only tools: risk_snapshot, verify_webhook, qualify_lead, authorize_action, and get_support_snapshot.
The wrapper also answers resources/list, resources/read, prompts/list, and prompts/get so directory scanners do not downgrade it for missing optional MCP surfaces.
Remote MCP uses a static X-API-Key header today. The MCP metadata now also publishes a Smithery config schema that maps apiKey to that header.
For Smithery compatibility only, POST /mcp?apiKey=$TXRISK_API_KEY is accepted when a connector cannot inject headers yet. Header auth remains the preferred path.
Mutable treasury, settlement verification, admin, and Bankr execution surfaces are not exposed through MCP.

curl -sS "$API_BASE_URL/.well-known/mcp/server.json" | jq

curl -sS -X POST "$API_BASE_URL/mcp" \
  -H "content-type: application/json" \
  -H "x-api-key: $TXRISK_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "txrisk-docs-example", "version": "1.0.0" }
    }
  }' | jq

curl -sS -X POST "$API_BASE_URL/mcp" \
  -H "content-type: application/json" \
  -H "x-api-key: $TXRISK_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "risk_snapshot",
      "arguments": {
        "walletAddress": "0xabc0000000000000000000000000000000000000",
        "chainId": 8453,
        "exposureUsd": 12.5,
        "signalWindowHours": 24
      }
    }
  }' | jq

Error Guide

Auth, payment, and retry semantics

Status	Error Code	Meaning	Client Action
400	validation_error or invalid_json	Request body or field schema is invalid.	Fix payload. Do not retry unchanged request.
402	payment_required	Public route requires an x402 payment payload.	Decode PAYMENT-REQUIRED, send PAYMENT-SIGNATURE, then retry unchanged body.
401 / 403	unauthorized / forbidden	Internal fallback/test-harness route is missing or has an invalid x-api-key.	Attach or rotate the internal key, then retry.
405	method_not_allowed	Endpoint requires POST.	Switch method to POST. No blind retries.
404	not_found	Unknown route.	Correct path before retrying.

Agent payment policy proof in under 10 minutes.