---
title: Documentation - AsterPay | The Trust Layer for AI Agent Payments
description: AsterPay API documentation. The trust, discovery and EUR-settlement layer for AI agent commerce. Seven core trust signals in a 5-layer framework, Trust Score 0-100, EUR via SEPA Instant. Know Your Agent (KYA), x402, MPP, x402r escrow, MiCA-aligned via licensed partners.
url: https://asterpay.io/docs/
source: https://asterpay.io/docs/
---
[← Back to AsterPay](/)

# Documentation

The trust, discovery and EUR-settlement layer for AI agent commerce. Seven core trust signals in a 5-layer framework, Trust Score 0–100. EUR in seconds.

### What is AsterPay?

AsterPay is the trust, discovery and EUR-settlement layer for AI agent commerce . Every payment passes through a 5-layer framework built from seven core trust signals: on-chain agent identity (ERC-8004), enterprise sanctions / AML screening, Trust Score computation, EUR settlement (EUR via SEPA Instant; GBP and USD via partner rails where available). MiCA-aligned via licensed European partners. Dual-protocol facilitator: x402 + MPP (Stripe / Tempo) + Google AP2 compatibility, plus x402r escrow / refunds.

5 layers: Verify → Screen → Score → Settle → Comply

## Quick Start

Get started in under 2 minutes. The Trust Score API is free — no signup needed.

### 1. Check an agent's trust score (free, no auth)

```
# Check any agent wallet — no API key, no payment
curl https://x402.asterpay.io/v1/agent/trust-score/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Response:
# { "trustScore": 34, "tier": "verified", "maxPerTx": 1000, ... }
```

### 2. (Optional) Create an account for the dashboard

You do not need an API key to call the API — free endpoints are open and paid endpoints authenticate by payment (see [Authentication](#authentication)). Only create an account at [app.asterpay.io](https://app.asterpay.io/signup) if you want a dashboard sandbox API key for usage tracking and analytics.

### 3. Test with the API Playground

Use the built-in [API Playground](https://app.asterpay.io/playground) to make test requests instantly — no code required.

### 4. Make your first x402 request

```
# The x402 flow: request → 402 → pay USDC → retry → 200

# Step 1: Request a paid endpoint (returns 402 + payment requirements)
curl https://x402.asterpay.io/v1/market/price/bitcoin

# Step 2: Use @x402/fetch to handle payment automatically
npm install @x402/fetch
```

### 5. Submit KYB for production EUR settlement

When you're ready to receive EUR, submit a [KYB application](https://app.asterpay.io/kyb) from the dashboard. Approval enables stablecoin → EUR settlement to your bank account.

## How x402 Works

The x402 payment flow:

- Client requests a paid API endpoint

- Server responds with `402 Payment Required` + payment details (USDC amount, address)

- Client signs a USDC `transferWithAuthorization` on Base

- Client retries the request with `PAYMENT-SIGNATURE` header

- Server verifies payment, settles on-chain, returns `200` with data

- (Optional) AsterPay converts USDC → EUR via SEPA Instant to your bank

### x402r: Escrow & Refund Protection

Trust-to-Refund Pipeline:

AsterPay's x402r integration adds on-chain escrow and automated refunds to x402 payments. The agent's KYA Trust Score determines the payment scheme:

- Score ≥ 70 → `exact` scheme — direct payment, instant settlement, no escrow

- Score < 70 or unknown → `commerce` scheme — funds held in on-chain escrow

- AsterPay's KYA Arbiter automatically verifies API delivery (HTTP status, response body, error detection)

- If delivery fails → automatic on-chain refund. If delivery verified → escrow releases to provider

Protocol: [x402r.org](https://x402r.org) — SDK: `@x402r/sdk`

## API Reference

### Know Your Agent (KYA) — FREE

GET
`/v1/agent/trust-score/:address`
FREE
Full agent trust assessment. Returns Trust Score (0-100), tier, breakdown of 7 components, ERC-8004 identity check, sanctions screening, and wallet analysis.

GET
`/v1/agent/verify/:address`
FREE
Quick ERC-8004 identity check. Returns whether the agent is registered in the on-chain identity registry on Base.

GET
`/v1/agent/tier/:address`
FREE
Fast tier lookup. Returns agent tier (open/verified/trusted/enterprise) and transaction limits.

POST
`/v1/agent/trust-score/batch`
FREE
Batch trust assessment for up to 50 agent addresses at once.

GET
`/v1/agent/framework`
FREE
Returns the full KYA framework documentation: layers, tiers, score components, and premium endpoints.

GET
`/v1/agent/audit/:address`
FREE
KYA audit snapshot. Returns raw inputs and score breakdown for third-party verification and compliance auditing.

GET
`/v1/agent/discovery`
FREE
Service discovery endpoint. Lists all available endpoints, payment methods (x402, MPP), and settlement capabilities.

### Agent Deep Analysis — PREMIUM (x402)

GET
`/v1/agent/deep-analysis/:address`
$0.015
Behavioral intelligence: velocity scoring, consistency analysis, funding source risk, and actionable recommendations (allow/limit/review/block).

POST
`/v1/agent/deep-analysis/batch`
$0.075
Batch deep analysis for up to 10 agents. Includes all behavioral signals and recommendations.

### Market Data

Machine-payable via x402 or MPP — no API key, no account. Each call carries its own USDC payment. `GET /v2/x402/crypto/prices` ($0.0075) returns an aggregated multi-token feed in one call.

GET
`/v1/market/price/:symbol`
$0.0075
Get current price, 24h change, market cap, and volume for any crypto asset.

GET
`/v1/market/ohlcv/:symbol`
$0.015
OHLCV candle data (1–90 days). Symbols: BTC, ETH, SOL, USDC, and 20+ more.

GET
`/v1/market/trending`
$0.0075
Trending coins with price, rank, and 24h change.

### AI Tools

POST
`/v1/ai/summarize`
$0.006
AI-powered text summarization.

POST
`/v1/ai/sentiment`
$0.006
Sentiment analysis on any text. Richer market-context variant: `POST /v2/x402/ai/sentiment` ($0.015).

POST
`/v1/ai/translate`
$0.03
AI translation between languages.

POST
`/v1/ai/fact-check`
FREE
Source-bounded fact-check: verify a claim against source text you supply. Does not search the web. Deep variant with claim decomposition: `POST /v2/x402/ai/fact-check/deep` ($0.075).

POST
`/v1/ai/code-review`
$0.075
Automated code review with suggestions.

### Crypto Analytics

GET
`/v1/crypto/wallet-score/:address`
$0.075
On-chain wallet reputation score.

GET
`/v1/crypto/token-analysis/:address`
$0.15
Deep token analysis with holder data and risk assessment.

GET
`/v1/crypto/whale-alerts`
$0.03
Real-time large transaction alerts.

### Utilities

POST
`/v1/util/qr-code`
FREE
Generate QR codes from any data. Free gateway endpoint.

### Settlement

GET
`/v1/settlement/estimate`
FREE
Get a real-time USDC → EUR conversion estimate.

GET
`/v1/settlement/quote`
FREE
Get a settlement quote with fees and delivery time.

### Facilitator (x402 v2)

POST
`/v2/x402/verify`
Verify an x402 payment payload.

POST
`/v2/x402/settle`
Settle an x402 payment on-chain.

GET
`/v2/x402/supported`
FREE
List supported payment schemes and networks.

### x402r — Escrow & Refunds

GET
`/v1/x402r/status`
FREE
x402r operator configuration, escrow parameters, and Trust-to-Scheme routing rules. Shows whether escrow-protected payments are active.

GET
`/v1/x402r/scheme/:address`
FREE
Determine which payment scheme an agent qualifies for based on KYA trust score. Score ≥ 70 → direct payment (exact). Score < 70 → escrow-protected (commerce, refundable).

POST
`/v1/x402r/arbiter/verify`
FREE
Automated delivery verification endpoint. Called after settlement to verify API response validity. KYA engine acts as arbiter — no human needed.

GET
`/v1/x402r/refunds/:hash`
FREE
Check refund status by payment hash. Returns escrow state, approved amount, and dispute resolution status.

GET
`/v1/x402r/info`
FREE
x402r protocol information and integration guide. SDK links, arbiter details, and trust-to-scheme documentation.

### Discovery & System

GET
`/discovery/resources`
FREE
x402 Bazaar resource discovery (ERC-8004 compatible).

GET
`/health`
FREE
Health check.

GET
`/docs`
FREE
Interactive Swagger API documentation.

## Authentication

One rule per surface — you almost never need an API key.

| Surface | Auth | How

| Free read endpoints | None | Plain HTTP GET. No key, no account.

| Paid endpoints | Pay-per-call (keyless) | x402 `PAYMENT-SIGNATURE` header, or MPP `Authorization: Payment`. No account.

| Dashboard & merchant features | API key | `Authorization: Bearer sk_...` — optional, only for dashboard-bound calls.

Live EUR payout requires KYB (handled once, at settlement — not at the API). Reads and per-call payments stay keyless and accountless.

### x402 Payment (primary)

All paid endpoints use the x402 protocol. No API key needed — payment is the authentication. Your client signs a USDC transaction and includes it in the request header.

### API Keys (optional, for tracking)

Create API keys in the [dashboard](https://app.asterpay.io/api-keys) to track usage, set rate limits, and view analytics.

```
curl -H "Authorization: Bearer sk_sand_your_key" \
https://x402.asterpay.io/v1/market/price/bitcoin
```

| Key Prefix | Environment | Description

| `sk_sand_` | Sandbox | Testing, no real payments

| `sk_live_` | Production | Real USDC payments + EUR settlement

## Errors

Every error returns the same JSON shape. The HTTP status tells you what to do; the body never leaks internal detail.

```
{
"error": "payment_identifier_conflict",
"message": "Human-readable explanation.",
"x402Version": 2
}
```

| Status | Error | Meaning & what to do

| `400` | `bad_request` / `payment_identifier_required` | Malformed request or a required field is missing. Fix the request — do not retry as-is.

| `402` | `Payment Required` | Paid endpoint hit without a valid payment. The body carries the x402 payment requirements (`accepts`, amount, network, asset). Sign and retry. A failed proof returns `402` with `Payment verification failed`.

| `404` | `not_found` | Unknown route or resource (e.g. an address with no data). Do not retry.

| `409` | `payment_identifier_conflict` | You reused a `payment-identifier` `id` with a different payment payload. Use a fresh `id` for a new charge (see Idempotency).

| `422` | `validation_error` | Request was well-formed but failed validation (bad amount, unsupported chain/asset, out-of-range parameter). Correct the input.

| `429` | `rate_limited` | Too many requests. Honour the `Retry-After` and `X-RateLimit-*` response headers and back off.

| `403` | `kya_blocked` | Know-Your-Agent gate denied the payer (sanctioned address or trust score below the endpoint's floor). Not retryable for that wallet.

| `503` | `settlement_unavailable` | A downstream rail (SEPA / settlement partner) is temporarily unavailable, or an escrow timed out. The charge is not finalised; retry later or re-quote.

| `500` | `internal_error` | Unexpected server error. Safe to retry with the same idempotency `id`; if it persists, contact support with the `X-Request-Id`.

## Idempotency

Paid calls are safe to retry without double-charging . AsterPay implements the x402 [payment-identifier](https://docs.x402.org/extensions/payment-identifier) extension, advertised in the `extensions` object of every paid `402` response.

Attach a unique `id` (16–128 chars) inside the payment payload. Then:

- Same `id` + same signed payload → the original `2xx` result is replayed from cache without re-settling on-chain . The replay carries an `X-Idempotency-Replayed: true` header.

- Same `id` + different payload → `409 payment_identifier_conflict`. Use a fresh `id` for each distinct charge.

- No `id` → normal flow. The underlying USDC authorization carries a one-time EIP-3009 nonce, so a fully identical replay still cannot settle twice on-chain — but for guaranteed exactly-once application results, always send an `id`.

Generate one `id` per logical operation (e.g. a UUID) and reuse it across network retries of that same operation.

## Supported Chains

| Chain | Stablecoins | Status

| Base | USDC, EURC | ✅ Primary

| Base Sepolia | USDC | ✅ Testnet

| Ethereum | USDC, EURC, EURCV | ✅ Supported

| Polygon | USDC | ✅ Supported

| Arbitrum | USDC | ✅ Supported

| Optimism | USDC | ✅ Supported

| Bitcoin Lightning | — (sats, sub-cent micropayments) | ✅ Supported

| Solana | USDC | 🚧 Roadmap

| XRPL | XRP, RLUSD | 🚧 Roadmap

| Monad | USDC | 🚧 Roadmap

## EUR Settlement

AsterPay converts your stablecoin earnings to EUR and sends them to your bank account.

- EUR: SEPA Instant — in your bank in seconds

- GBP: Faster Payments — on the roadmap

- Stablecoins: USDC, EURC (Circle), EURCV (SG-FORGE / Soci&eacute;t&eacute; G&eacute;n&eacute;rale)

- Requirements: Approved KYB + bank account on file

- MiCA: MiCA-aligned — settlement routed via licensed European partners (AsterPay operates as a technical service provider)

## Agent Trust Score

Every agent that interacts with AsterPay receives a Trust Score (0–100). The score is built from seven core signals organised under a 5-layer framework (VERIFY / SCREEN / SCORE / SETTLE / COMPLY). Two optional endpoint-quality signals can additionally contribute when the caller passes `?endpoint={URL}` — the authoritative machine-readable spec is [/v1/agent/framework](https://x402.asterpay.io/v1/agent/framework):

| Signal | Max Points | Source

| Wallet Age | 15 | On-chain (first tx)

| Wallet Activity | 15 | Transaction count

| Sanctions Screening | 20 | Chainalysis Sanctions Oracle, on-chain (OFAC, EU, UN)

| Agent Identity | 20 | ERC-8004 on-chain registry

| Operator KYB | 20 | Off-chain KYB & UBO verification

| Payment History | 5 | AsterPay track record

| Trust Bond | 5 | Cryptographically attested USDC collateral

Scores map to access tiers (synchronised with the machine-readable spec at [/v1/agent/framework](https://x402.asterpay.io/v1/agent/framework)):

| Tier | Score | Max Per Call | Daily Cap | Live

| Open | 0–19 | $1 | $10 | ✓

| Verified | 20–49 | $1,000 | $5,000 | ✓

| Trusted | 50–79 | $10,000 | $50,000 | ✓

| Enterprise | 80–100 | Negotiated | Negotiated | Q3 2026

Trust tier limits are reviewed quarterly. AsterPay reserves the right to escrow, hold or refuse transactions where risk monitoring requires it — see [Terms § 4](/terms/).

## SDKs

### asterpay (Python)

Full Python SDK with async support. CrewAI and LangChain integrations included.

```
# Install
pip install asterpay

# Usage
from asterpay import AsterPay

client = AsterPay(api_key="sk_live_...")
score = client.discovery.trust_score("0xd8dA...96045")
print(score.trust_score, score.tier) # 34, "verified"

# Async
import asyncio
from asterpay import AsyncAsterPay

async def main():
client = AsyncAsterPay(api_key="sk_live_...")
price = await client.market.get_price("bitcoin")
print(price)
```

### asterpay-openai-agents (Python)

Payment tools for OpenAI Agents SDK — give your AI agents the ability to pay.

```
# Install
pip install asterpay-openai-agents

# Usage
from agents import Agent
from asterpay_agents import get_asterpay_tools, AsterPayWallet

wallet = AsterPayWallet(
private_key=os.environ["AGENT_KEY"],
network="base",
daily_limit=10.0
)

agent = Agent(
name="Shopping Assistant",
tools=get_asterpay_tools(wallet)
)
```

### @asterpay/attest (CLI & SDK — EU AI Act)

Scan your TypeScript project for AI SDK imports, run compliance signal checks, and generate EU AI Act documentation. August 2, 2026 deadline.

```
# Zero install — try now
npx @asterpay/attest scan

# Check compliance signals
npx @asterpay/attest check

# Generate Annex IV docs
npx @asterpay/attest docs -o ./compliance
```

[GitHub](https://github.com/AsterPay/attest) · [npm](https://www.npmjs.com/package/@asterpay/attest) · MIT License

## Agent-to-Agent Payments (Payment Rail Propagation)

AsterPay's MCP server includes two tools for the x402 "virus machine" pattern — payment rails that propagate automatically between agents:

### agent_pay — Pre-payment trust gate

Before paying another agent, call `agent_pay` to verify they're not sanctioned and check their trust tier. Returns payment instructions if safe, blocks if sanctioned.

```
# Via MCP: agent checks trust before sending USDC
# → Returns: trust score, sanctions status, payment instructions
# → Blocks sanctioned addresses automatically
# → Recommends escrow for low-trust agents (score Returns AsterPay's payment rail as a JSON-LD document. Install this rail to pay any AsterPay-connected agent, then forward it to every agent you interact with.

```
# Returns JSON-LD payment rail with:
{
"@context": { "x402": "https://x402.org/schema/" },
"x402:signatureScheme": "ECDSA-SHA256",
"x402:supportedNetworks": ["Base", "Ethereum", "Polygon", ...],
"asterpay:trustScoring": { "scoreRange": "0-100" },
"asterpay:settlement": { "currencies": ["EUR", "USD", "GBP"] }
}
```

Discovery: [.well-known/x402.json](https://asterpay.io/.well-known/x402.json) (JSON-LD) · Signature: ECDSA-SHA256

## Code Examples

### Trust Score — cURL (free)

```
# Get full trust assessment for any wallet
curl https://x402.asterpay.io/v1/agent/trust-score/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Quick tier check
curl https://x402.asterpay.io/v1/agent/tier/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Batch check 10 agents at once
curl -X POST https://x402.asterpay.io/v1/agent/trust-score/batch \
-H "Content-Type: application/json" \
-d '{"addresses": ["0xd8dA...", "0xABC..."]}'
```

### Trust Score — Python

```
from asterpay import AsterPay

client = AsterPay()
result = client.discovery.trust_score("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")

if result.tier in ("trusted", "enterprise"):
process_payment(result.wallet)
elif result.screening.sanctioned:
block_wallet(result.wallet)
else:
require_additional_verification(result.wallet)
```

### Node.js — Fetch with x402 payment

```
import { fetchWithPayment } from '@x402/fetch';

const response = await fetchWithPayment(
'https://x402.asterpay.io/v1/ai/summarize',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text: 'Your text here...' })
},
wallet
);
```

### Python — Market data

```
import requests

# Free endpoint (no payment needed)
r = requests.get("https://x402.asterpay.io/v1/settlement/estimate",
params={"amount": "100"})
print(r.json()) # { "eur": "92.50", "rate": 0.925, ... }
```

### cURL — Check supported networks

```
curl https://x402.asterpay.io/v2/x402/supported
```

## Webhooks

Configure webhooks in the [dashboard](https://app.asterpay.io/webhooks) to receive real-time notifications.

```
// Webhook payload example
{
"event": "settlement.completed",
"transaction_id": "txn_abc123",
"amount_usdc": "100.00",
"amount_eur": "92.50",
"status": "settled",
"sepa_reference": "ASTER-2026-0213"
}
```

## Dashboard

The [AsterPay Dashboard](https://app.asterpay.io) gives you full control:

- API Keys — Create and manage sandbox & production keys

- Playground — Test all endpoints interactively (including Trust Score)

- Usage Analytics — Real-time charts for requests, revenue, and latency

- Transactions — Track stablecoin payments and EUR settlements

- Budgets — Set daily/weekly/monthly spending limits for AI agents

- CRM — Lead pipeline and outreach tracking

- Webhooks — Configure event notifications

- Team — Invite team members with role-based access

- KYB — Submit your business verification for production EUR settlement

## Infrastructure Partners

- [InsumerAPI](https://insumermodel.com) — On-chain attestation provider across 32 chains. Powers the credential and activity layers of our KYA Trust Score.

## Support

We're here to help you integrate fast.

- Email: [samantha@asterpay.io](mailto:samantha@asterpay.io)

- Community: [t.me/asterpaycommunity](https://t.me/asterpaycommunity)

- Interactive API docs: [Swagger UI](https://x402.asterpay.io/docs)
