Credit Score API · quickstart
Score any autonomous agent for 0.01 USDC per call, paid over the x402 protocol on Algorand. No API key, no signup — the payment is the auth.
GET https://cred402-1.onrender.com/v1/x402/credit-score/:agentId
| Field | Value |
|---|---|
| Price | 0.01 USDC — 10000 micro-USDC per call |
| Protocol | x402 v2, exact scheme |
| Settlement chain | Algorand (USDC ASA) |
| Facilitator | GoPlausible (facilitator.goplausible.xyz) |
| Auth | None — the x402 payment authorizes the call |
| Path param | agentId — the Cred402 agent identifier to score (e.g. EvidenceSellerAgent) |
The endpoint follows the standard x402 402 → sign → 200 lifecycle:
| Step | What happens |
|---|---|
| 1 | Your agent requests the endpoint. It responds 402 Payment Required with a PAYMENT-REQUIRED header declaring the exact price, receiver, network, and USDC asset. |
| 2 | The x402 client signs a USDC transfer on Algorand for exactly the declared amount and receiver. |
| 3 | The request is retried with a PAYMENT-SIGNATURE header. The facilitator settles the payment and the endpoint returns 200 with the credit report and a PAYMENT-RESPONSE header. |
| 4 | The report includes a content-addressed receipt, independently reconciled against the Algorand Indexer and anchored to Casper. |
The status probe is free, secret-free, and never touches a wallet. Use it to pin your client policy.
curl -sS https://cred402-1.onrender.com/v1/x402/algorand/status
It returns the live price_micro_usdc, pay_to receiver, network, usdc_asset, and finality settings. Copy those into explicit client constraints:
export CRED402_ALGORAND_CLIENT_NETWORK=testnet export CRED402_ALGORAND_EXPECTED_PAY_TO=<58-char receiver from status> export CRED402_ALGORAND_EXPECTED_PRICE_MICRO_USDC=10000 export CRED402_ALGORAND_MAX_PRICE_MICRO_USDC=10000
Inspect the unpaid 402 challenge directly (no payment). The -i flag shows the PAYMENT-REQUIRED header your client will decode and sign against:
curl -i -sS https://cred402-1.onrender.com/v1/x402/credit-score/EvidenceSellerAgent HTTP/1.1 402 Payment Required PAYMENT-REQUIRED: <base64 x402 challenge: price, payTo, network, asset> Content-Type: application/json { "error": "payment_required", "message": "Pay with USDC on Algorand to access this credit report.", "price_micro_usdc": "10000", "network": "algorand:416002" }
PAYMENT-SIGNATURE header. In practice, use the
official x402 client (below), which performs the sign-and-retry for you.
Install the official x402 packages, then let the client run the full 402 → sign → retry cycle under your pinned policy.
npm i @x402/core @x402/avm @x402/fetch
import { ExactAvmScheme, toClientAvmSigner } from "@x402/avm"; import { wrapFetchWithPaymentFromConfig } from "@x402/fetch"; // testnet CAIP-2 + USDC ASA — verify against /v1/x402/algorand/status const network = "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="; const usdcAsset = 10458941; const endpoint = "https://cred402-1.onrender.com/v1/x402/credit-score/EvidenceSellerAgent"; // Only read the key after you have approved the exact price + receiver. const signer = toClientAvmSigner(process.env.CRED402_ALGORAND_CLIENT_PRIVATE_KEY!); const paidFetch = wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network, client: new ExactAvmScheme(signer) }], // Reject anything that is not exactly your expected price/receiver/asset. paymentRequirementsSelector: (version, accepts) => { const r = accepts[0]; if (version !== 2 || r.scheme !== "exact" || r.asset !== usdcAsset || r.amount !== "10000") { throw new Error("x402 challenge did not match pinned policy"); } return r; }, }); const res = await paidFetch(endpoint, { headers: { accept: "application/json" } }); const report = await res.json(); console.log(report.score, report.risk_band, report.payment.external_receipt_url);
A complete, policy-hardened example (interactive approval, receipt + usage-feed verification) ships in the repo at examples/algorand-paid-score/typescript.ts.
python -m pip install "x402-avm[avm,httpx]==2.0.2"
import os, httpx from x402_avm import ExactAvmScheme, to_client_avm_signer from x402.clients.httpx import x402_payment_hooks network = "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" # verify via /status endpoint = "https://cred402-1.onrender.com/v1/x402/credit-score/EvidenceSellerAgent" signer = to_client_avm_signer(os.environ["CRED402_ALGORAND_CLIENT_PRIVATE_KEY"]) client = httpx.Client() client.event_hooks = x402_payment_hooks( schemes=[{"network": network, "client": ExactAvmScheme(signer)}], ) resp = client.get(endpoint, headers={"accept": "application/json"}) report = resp.json() print(report["score"], report["risk_band"], report["payment"]["external_receipt_url"])
Full example: examples/algorand-paid-score/python.py in the repo.
CRED402_ALGORAND_CLIENT_PRIVATE_KEY (base64, 64 bytes)
only in the terminal that runs the call. Never commit it or pass a mnemonic. The payer wallet
must be funded and opted into the network's USDC ASA.
200 OK · cred402.credit-score.v1
| Field | Type | Meaning |
|---|---|---|
agent_id | string | The scored agent identifier |
score | integer 0–100 | Credit score |
risk_band | enum | low · moderate · elevated · high |
probability_of_default | number 0–1 | Calibrated PD estimate |
eligible | boolean | Whether the agent clears the eligibility threshold |
reason_codes | string[] | Machine-readable drivers of the decision |
payment | object | x402 settlement details + receipt (below) |
payment object{
"protocol": "x402-v2",
"network": "algorand:416002",
"asset": 10458941,
"amount_micro_usdc": "10000",
"transaction": "ALGORAND_TX_ID",
"external_receipt_id": "0x…",
"external_receipt_url": "https://cred402-1.onrender.com/v1/x402/external-receipts/0x…",
"algorand_finality": "confirmed", // pending | confirmed | not_found | mismatch | unavailable
"casper_anchor_status": "finalized" // anchored | finalized | challenged | not_recorded
}
Fetch external_receipt_url to independently verify the content-addressed receipt, and cross-check it in the public usage feed at GET /v1/x402/algorand/usage.
| Code | Meaning |
|---|---|
200 | Paid and settled — credit report returned |
402 | Payment required — decode PAYMENT-REQUIRED, sign, retry |
404 | Unknown agentId |
409 | Payment proof replay conflict or already-rejected proof |
202 | Settlement in progress — do not pay again; poll the attempt URL |
502 | Facilitator unavailable or settlement outcome indeterminate — reconcile via the attempt URL, do not repay |
503 | Algorand x402 not configured on this deployment |
PAYMENT-SIGNATURE replays
the original result rather than charging twice. On a 202/502, poll the
returned payment_attempt_url instead of paying again.
The endpoint is registered in the x402 Bazaar discovery directory with the
tags credit-score, agentic-finance, algorand, and
x402-global-challenge, so x402-aware agents can find and price it automatically.
| Live status | /v1/x402/algorand/status |
| Usage feed | /v1/x402/algorand/usage |
| OpenAPI spec | packages/openapi/cred402.v1.yaml (repo) |
| Pricing | /pricing |