Owner directive (2026-11-11): submit a single project to the NEAR Hackathon instead of two separate entries from the same person. Vendors Ration's NEAR audit-anchor work (github.com/caelum0x/ration, commit cff0ed3 + follow-ups) into ration-anchor/ as a first-class component: - contracts-near/audit_anchor (NEAR Rust contract, 5/5 cargo tests green, target/ deleted) - signer/ — a new, self-contained Go module (no dependency on Ration's other services or go.work) with the hand-rolled NEAR transaction signer + JSON-RPC client (cross-checked byte-for-byte against near-api-js) and the hash-chained audit ledger it anchors; 15/15 Go tests green (go test ./... -race) - docs/ and media/ — Ration's original pitch deck, demo recordings, and submission checklist Re-verified live via raw NEAR Testnet JSON-RPC this pass: ration-anchor-286ca315f1.testnet still deployed and queryable, the deliberate replay-rejection transaction still fails with nearcore's own "sequence must strictly advance" panic — no redeploy needed. Provenance notes added throughout (package doc comments, lib.rs header, README) crediting the origin repo. README.md and HACKATHON.md rewritten to tell one story: Cred402's SpendGuard enforces the protocol-level spending limit, the vendored Audit Anchor proves the tamper-evident spend history, both independently verifiable on NEAR Testnet. No mainnet claims anywhere (see prior overclaim fix 524f2dd). cred402's own build (npm run typecheck) and existing tests are untouched. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
16 KiB
Cred402 — SpendGuard + Audit Anchor × NEAR Hackathon (Nov 1-14, 2026)
ONE combined submission (owner decision, 2026-11-11): this is now a
single NEAR Hackathon entry, not two. It was previously planned as two
separate entries from the same person (this repo, plus
Ration's own audit-anchor work).
The owner decided to submit only this repo to the hackathon, with
Ration's NEAR audit-anchor work vendored in as a first-class component
at ration-anchor/ — see
ration-anchor/README.md for the full
provenance note. Ration's own repo and its separately-drafted packet
still exist and are unaffected; they are simply not the thing being
submitted to this hackathon anymore.
Tracks
Agent Economy and AI Security & Defense (multi-select, if the submission form allows it — if it only allows one, Agent Economy is the primary track).
Cred402 already is an agent paying for a service: an AI agent calls a
credit-score API, gets an HTTP 402 Payment Required challenge (the x402
protocol), pays, and receives the paid result. This submission adds a
second, independent settlement rail — native NEAR on NEAR Testnet —
alongside the project's existing Algorand x402 integration, so an agent can
pay for the same resource with whichever chain it already holds funds on.
Cred402 is also a direct fit for AI Security & Defense: SpendGuard turns an agent's verified revenue into a protocol-enforced spending limit (a real NEAR Function Call Access Key allowance — nearcore itself caps spend, not just application code), and the vendored-in Ration Audit Anchor journals every spend decision into a hash-chained audit trail anchored on NEAR, so a counterparty can independently verify both the limit and the history on one chain.
What it does
Cred402 is a pay-per-call credit-score API for AI agents. An agent calls:
GET /v1/x402/near/credit-score/:agentId
and gets back a JSON credit report — score, probability of default, risk
band, eligibility, reason codes — paid for per-call in native NEAR
(testnet), using the x402 protocol's standard 402 Payment Required
challenge/response flow. The same resource is also sellable via Algorand
USDC (/v1/x402/credit-score/:agentId, pre-existing) and QIE
(/v1/x402/qie/credit-score/:agentId, pre-existing) — this hackathon adds
the NEAR rail.
The problem it solves: AI agents that transact with each other (or with paid APIs) need a way to assess counterparty trustworthiness and a way to actually pay per call without a subscription or an API key issued by a human. Cred402 solves both: it is itself an x402-paid API (proving the pattern works), and its payload is exactly the signal — a credit score, default probability, and reason codes — an agent-economy platform needs to decide whether to extend credit, accept a job, or route a payment to another agent.
What NEAR tooling this submission uses, and how
- NEAR as a settlement rail for x402.
lib/x402/near_gateway.tsis a from-scratch x402 v2exactscheme for NEAR. No@x402/nearpackage exists yet, so this reuses@x402/core's chain-agnostic wire format (header codecs +PaymentRequirements/PaymentPayloadtypes — the same types Cred402's Algorand and QIE integrations use) and adds NEAR-specific verification. - No third-party facilitator — Cred402 verifies itself against NEAR RPC.
lib/x402/near_finality.tsreads a payer's claimed transaction back from the configured NEAR RPC (EXPERIMENTAL_tx_status+block), confirms it executed successfully, confirms the signer/receiver/amount match, and requires a minimum finality depth before calling the paymentconfirmed. This is the direct chain-abstraction pattern NEAR's docs describe for a resource server that wants to accept NEAR-native payments without depending on an external facilitator. - NEAR account signing (near-api-js), Chain-Signatures-ready. The buyer
example (
examples/near-paid-score/typescript.ts) usesnear-api-jsto sign and submit a native NEARTransferaction from a NEAR Testnet account. Because the server only ever verifies an already-signed NEAR transaction hash, it is already compatible with NEAR Chain Signatures without any server change: an agent that holds a key on a different chain (or no NEAR key at all) could have a NEAR MPC network derive and sign the sameTransfertransaction on its behalf, and Cred402 would verify it identically. This extension point — and the equally compatible NEAR Intents path (swap any asset into the exact NEAR amount before callingsignAndSendTransaction) — is documented indocs/near_x402.mdrather than mocked, to be honest about what is wired up today versus what the architecture already supports.
SpendGuard — the AI Security & Defense complement (NEAR smart contract)
Alongside the x402 payment rail above, this submission also ships a real
NEAR smart contract, contracts-near/spend_guard, built specifically for
the AI Security & Defense angle this file mentions above: turning an
agent's verified x402 revenue into a protocol-enforced spending
permission, not just an application-level check.
policy.rsunderwrites a credit line from an agent's metrics (ported from Cred402's existing CasperRiskPolicyManager).exposure.rs(ExposureBook) tracks that credit line against a global exposure cap (ported from Cred402's TypeScriptGlobalExposureManager), so an agent can never be authorized beyond its real cap across chains.spend_key.rsturns an approved credit line into a real NEAR Function Call Access Key whoseallowancenearcore itself enforces — the cap is a protocol guarantee, not just a contractrequire!.scam_detection.rsis the circuit breaker: a dispute-rate spike freezes the agent and revokes its live key outright, independent of remaining budget — proven against real nearcore access-key deletion, not mocked.repay_credit_lineturns the approved credit line into an actual revolving credit line: an admin-verified repayment reduces the agent's outstanding exposure, the other half of a real credit score for an agent (draw, repay, draw again), not a one-shot budget.top_up_allowance(added 2026-11-05) closes the loop end to end: it re-reserves exactly the headroom a repayment freed (capped by the agent's own policy-approvedmax_allowed, never more) and re-mints the SAME still-active Function Call Access Key with a fresh on-chain allowance — so an agent can draw, repay, top up, and draw again on one continuously-live key, never needing a new identity or a new key.
Real, live proof, not unit tests in isolation: tests/sandbox.rs is a
near-workspaces integration test against a genuinely running local
nearcore node — deploy → policy → capped spend key → real spends → a real
on-chain repay_credit_line call with before/after get_exposure proof
that outstanding exposure actually zeroes out on the live contract → a real
on-chain top_up_allowance call that restores exactly that freed headroom
and re-mints the agent's original key → a real spend_to_seller call that
succeeds again on that SAME key, past the point its original allowance was
exhausted → a dispute spike → circuit-breaker freeze → the revoked key's
next call rejected by nearcore itself, even with budget left. Run it with:
cd contracts-near/spend_guard
cargo near build non-reproducible-wasm
cargo test --test sandbox -- --nocapture
A real NEAR protocol constraint found while building top_up_allowance
(not hidden, not worked around): nearcore's AddKey action unconditionally
rejects a public key that already exists on the account
(ActionError::AddKeyAlreadyExists, confirmed live against a running local
nearcore node) — there is no "update an access key's allowance" action in
the protocol. So topping up an existing key means delete_key then
add_access_key_allowance in the same receipt (same-account
self-actions, which nearcore always applies atomically and in order), not
a second AddKey call. See spend_key::retop_spend_key.
Also re-verified against the real, already-deployed public NEAR Testnet
contract (spendguard-024e8dd6f7.testnet, upgraded in place via npm run near:spend-guard:redeploy — a DeployContract action replaces code only,
never storage, so every prior agent/exposure record survived untouched):
25/25 real spend_to_seller calls, a real repay_credit_line call, a real
top_up_allowance call that restored the exact freed headroom, one more
real spend_to_seller call that succeeded on that SAME original key, a
dispute spike, a freeze, and a rejected post-freeze call — all against the
live public network, not just the local sandbox. Run it yourself with npm run demo:near-spend-guard (needs .secrets/near_spend_guard_credentials.json
from a prior npm run near:spend-guard:deploy).
🎬 Watch it without running anything: a real, unedited recording of that
exact live-Testnet loop (build → tests → sandbox integration test → all 25
spend calls → repay → top-up → draw-again → dispute spike → freeze →
rejected post-freeze call) is already in the repo —
media/cred402-near-spend-guard-demo.mp4
(17s, captured with asciinema/agg, raw .cast source at
media/cred402-near-spend-guard-demo.cast).
A second real, judge-relevant finding from this same run: NEAR's own
legacy public RPC (rpc.testnet.near.org) now rejects most calls with
-429 "WARNING! THIS ENDPOINT IS DEPRECATED!". Every default RPC URL in
this repo (lib/x402/near_networks.ts, near_spend_guard_client.ts,
scripts/near_spend_guard_deploy.ts) now defaults to FastNear's free
public RPC (rpc.testnet.fastnear.com) instead — CRED402_NEAR_RPC_URL
still overrides either way. If you cloned this repo before 2026-11-05 and
hit a -429 running the "How to run it" steps below, pull latest or set
CRED402_NEAR_RPC_URL=https://rpc.testnet.fastnear.com yourself.
Audit Anchor — the other half of the AI Security & Defense story (ration-anchor/)
SpendGuard above enforces how much an agent may spend. This submission's other NEAR component enforces why it spent, tamper-evidently: every spend decision gets journaled into a real append-only, hash-chained audit trail, and the trail's current tip is anchored to a second NEAR smart contract.
This component — contract, hand-rolled Go NEAR transaction signer (no
maintained Go NEAR SDK exists; cross-checked byte-for-byte against the
real near-api-js reference implementation), anchoring service, tests,
and demo recordings — was originally built in
Ration, a separate real AI-agent
spend-control product by the same author. It is vendored into this repo
at ration-anchor/ as a first-class part of this
single combined submission (owner decision, 2026-11-11) — see
ration-anchor/README.md for the full
provenance note, build/test instructions, and fresh live-verification
evidence.
Deployed live on NEAR Testnet: ration-anchor-286ca315f1.testnet. A real
deliberate replay attempt against it was rejected by nearcore itself
(Smart contract panicked: audit_anchor: sequence must strictly advance past the last anchored sequence (stale or replayed anchor rejected)),
re-confirmed via raw JSON-RPC this pass — not just rejected by
application code. 15/15 Go tests green (go test ./... -race), 5/5 Rust
contract tests green (cargo test --lib).
Together, SpendGuard + Audit Anchor mean a counterparty dealing with an agent backed by Cred402 can verify, on NEAR, both the spending limit that constrained it and the tamper-evident history of what it actually did — without trusting Cred402's own database for either claim.
How to run it (for judges)
git clone https://github.com/caelum0x/cred402.git
cd cred402
npm install
npm test # 450/450 green, including all 14 NEAR tests. (A
# test/mcp_sdk.test.ts stdio-handshake test has
# intermittently timed out under heavy host load in
# some environments in the past — unrelated to the
# x402/NEAR payment path either way.) Re-verified
# 2026-11-05, 450/450.
npm run typecheck # clean
1. Start the server with the NEAR route enabled (testnet, no real funds needed to see the 402 challenge):
CRED402_NEAR_PAY_TO=cred402.testnet npm run start
2. See the free, secret-free status probe:
curl -s http://localhost:4021/v1/x402/near/status | jq
3. See the x402 402 Payment Required challenge (no payment, no key):
curl -i http://localhost:4021/v1/x402/near/credit-score/EvidenceSellerAgent
You'll get an HTTP 402 with a PAYMENT-REQUIRED header — a base64-encoded
x402 v2 challenge naming the NEAR network, the native-NEAR asset, the exact
price in yoctoNEAR, and the pay-to account.
4. Run a real end-to-end paid call on NEAR Testnet (free testnet account at near-faucet.io, no mainnet funds):
export CRED402_NEAR_CLIENT_URL=http://localhost:4021/v1/x402/near/credit-score/EvidenceSellerAgent
export CRED402_NEAR_EXPECTED_PAY_TO=cred402.testnet
export CRED402_NEAR_CLIENT_ACCOUNT_ID=yourname.testnet
export CRED402_NEAR_CLIENT_PRIVATE_KEY=ed25519:YOUR_SECRET_KEY
npx tsx examples/near-paid-score/typescript.ts
This signs and submits a real NEAR Testnet transaction, retries the paid
request with the resulting proof, and prints the verified receipt. See
examples/near-paid-score/README.md
for the full walkthrough and
docs/near_x402.md for the protocol and
architecture writeup.
What's new in this submission (files)
lib/x402/near_networks.ts,near_rpc.ts,near_finality.ts,near_payment_attempt_store.ts,near_gateway.ts— the NEAR x402 resource server, self-verifying settlement, and durable exact-once replay protection.api/near_x402_routes.ts,api/near_receipt_anchor.ts— HTTP routes (/v1/x402/near/status,/v1/x402/near/usage,/v1/x402/near/payments/:id,/v1/x402/near/credit-score/:agentId) and Casper-rooted Universal Receipt anchoring, wired intoapi/server.tsandapi/state.tsalongside the existing Algorand/QIE routes (none removed or modified).examples/near-paid-score/typescript.ts(+ README) — a real buyer that signs and submits a NEAR Testnet transaction withnear-api-js.test/near_x402.test.ts— 14 new tests (config validation, the 402 challenge shape, payment-signature validation, the payment attempt store, and NEAR RPC finality checks against a mocked RPC) — TDD, all green; typecheck clean. Full suite is 450/450 green (see "How to run it" above). Also verified end-to-end against the real NEAR Testnet RPC and a real on-chain payment, not just unit tests — see "Verification" indocs/near_x402.md.docs/near_x402.md— protocol writeup, Chain Signatures / NEAR Intents extension points, Mainnet release checklist.
Existing Algorand (examples/algorand-paid-score/, /v1/x402/algorand/*)
and QIE (/v1/x402/qie/*) integrations are untouched.
contracts-near/spend_guard/— the SpendGuard contract (policy.rs,exposure.rs,spend_key.rs,scam_detection.rs,lib.rs), 18/18 unit tests green, plustests/sandbox.rs, a realnear-workspacessandbox integration test proving the full earn→spend→repay→top-up→spend→freeze loop against a genuinely running local nearcore node.ration-anchor/— Ration audit anchor, now part of Cred402 (added 2026-11-11, vendored fromcaelum0x/rationcommitcff0ed3+ follow-ups):contracts-near/audit_anchor/(NEAR contract, 5/5 Rust tests green),signer/(a self-contained Go module — hand-rolled NEAR transaction signer + JSON-RPC client + the hash-chained audit ledger it anchors, 15/15 Go tests green,go test ./... -race),docs/andmedia/(Ration's original pitch deck, demo recordings, and submission checklist). Seeration-anchor/README.mdfor the full provenance note and fresh live-verification evidence.