Cred402

Cred402

Credit Score API · quickstart

Credit Score API

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.

Checking live endpoint status…
Endpoint Payment flow Read the price curl TypeScript Python Response Errors Discovery

Endpoint

GET https://cred402-1.onrender.com/v1/x402/credit-score/:agentId
FieldValue
Price0.01 USDC — 10000 micro-USDC per call
Protocolx402 v2, exact scheme
Settlement chainAlgorand (USDC ASA)
FacilitatorGoPlausible (facilitator.goplausible.xyz)
AuthNone — the x402 payment authorizes the call
Path paramagentId — the Cred402 agent identifier to score (e.g. EvidenceSellerAgent)
Always pin the price and receiver from the live 402 challenge (or the free status probe below) before signing. Never hardcode a receiver address in production; read it at request time and reject anything that does not match your expected policy.

The x402 payment flow

The endpoint follows the standard x402 402 → sign → 200 lifecycle:

StepWhat happens
1Your agent requests the endpoint. It responds 402 Payment Required with a PAYMENT-REQUIRED header declaring the exact price, receiver, network, and USDC asset.
2The x402 client signs a USDC transfer on Algorand for exactly the declared amount and receiver.
3The 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.
4The report includes a content-addressed receipt, independently reconciled against the Algorand Indexer and anchored to Casper.

Read the price — free, no wallet

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

Quickstart: curl

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"
}
Completing the payment with raw curl means hand-building and signing an Algorand USDC transfer and base64-encoding the PAYMENT-SIGNATURE header. In practice, use the official x402 client (below), which performs the sign-and-retry for you.

Quickstart: TypeScript

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.

Quickstart: Python 3.10+

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.

Key safety: set 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.

Response schema

200 OK · cred402.credit-score.v1

FieldTypeMeaning
agent_idstringThe scored agent identifier
scoreinteger 0–100Credit score
risk_bandenumlow · moderate · elevated · high
probability_of_defaultnumber 0–1Calibrated PD estimate
eligiblebooleanWhether the agent clears the eligibility threshold
reason_codesstring[]Machine-readable drivers of the decision
paymentobjectx402 settlement details + receipt (below)

The 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.

Status codes

CodeMeaning
200Paid and settled — credit report returned
402Payment required — decode PAYMENT-REQUIRED, sign, retry
404Unknown agentId
409Payment proof replay conflict or already-rejected proof
202Settlement in progress — do not pay again; poll the attempt URL
502Facilitator unavailable or settlement outcome indeterminate — reconcile via the attempt URL, do not repay
503Algorand x402 not configured on this deployment
Every paid attempt is idempotent: re-sending the same PAYMENT-SIGNATURE replays the original result rather than charging twice. On a 202/502, poll the returned payment_attempt_url instead of paying again.

Discovery

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 specpackages/openapi/cred402.v1.yaml (repo)
Pricing/pricing