Priors API

The credit record of any agent enrolled in Priors: who backs it, its line, what it has repaid, its score, and the pool's and the stock vault's figures; and images and 5-second video clips made to order. Each endpoint has its own price, from 0.02 to 0.45 USDG a call on Robinhood Chain, paid per request with x402 v2. No account, no key.

Endpoints

request	price	returns
`GET /v1/report/:agentId`	0.03 USDG	Priors credit report: identity, backer, line, available, record, score, open loans and recent history of one ERC-8004 agent, and the stock collateral behind a stock line
`GET /v1/score/:agentId`	0.03 USDG	Priors score of one ERC-8004 agent, with its default and freeze flags, and the Priors Score v2 breakdown (rung, components, x402 income) when published
`GET /v1/file/:agentId`	0.10 USDG	Priors due-diligence file on one ERC-8004 agent: its credit report, repayment profile, Score v2 and next rung, its owner's other agents and record, its backer's ledger, and the flags to read before a deal
`GET /v1/explain/:agentId`	0.02 USDG	Priors Score v2 of one agent explained: each part with its points, its maximum and the room left, and the next rung with what it still needs, in plain words
`POST /v1/screen`	0.05 USDG	Priors screen of up to 50 agent ids or owner addresses in one call: for each, whether Priors knows it, a verdict (defaulted, late, frozen, borrowing, repaid, enrolled, unknown), its score and Score v2 rung
`GET /v1/wallet/:address`	0.03 USDG	Priors footprint of one address: the agents it owns and their verdicts, the loans it took as an owner, whether a default marked it, what it lent to the pool or staked, and its owner's Ethos score
`GET /v1/income/:agentId`	0.03 USDG	Priors income statement of one agent: the fees it paid as a borrower, its fee share as a backer, its x402 income over 30 days (from Score v2), and month by month for the last 6 months
`GET /v1/pool/day`	0.02 USDG	Priors pool figures for one UTC day (today so far by default): loans borrowed and repaid, fees and their split, defaults, agents active and joined, lenders' deposits, and for today the pool now
`POST /v1/watch`	0.03 USDG	Priors watch on up to 50 agents: each one's open loans with their due dates and state (on time, due within 24 hours, late, defaultable) and its last default
`GET /v1/late`	0.02 USDG	Every Priors loan past due now (late, or defaultable after its grace), with its agent and backer, and the defaults of the last 30 days
`GET /v1/backer/:agentId`	0.05 USDG	Priors ledger of one backer (a pool root): the loans it backed, repaid, late and defaulted, the agents it backs now with their lines and state, and its fee share
`GET /v1/stock-line/:symbol`	0.02 USDG	Priors stock line sizing: how many tokens of one stock the vault needs for a line of that size (?line=<USDG>), at the token's loan-to-value and the vault's own valuation, and whether it fits the vault's limits and holds now
`GET /v1/stocks/holds`	0.02 USDG	Priors stock vault holds: each accepted stock token, whether it takes new lines now and why not (its hold), its loan-to-value, its room under its cap, and the vault's largest line and room this week
`GET /v1/credit/:agentId`	0.03 USDG	Priors credit history of one agent: every loan on both pools, newest first, 100 a page (?page=), each with its dates, state and the transactions that prove it on Robinhood Chain
`POST /v1/media/image`	0.05 USDG	Priors image from a text prompt (Higgsfield Soul 2, 1080p, one image), under strict content rules checked before payment: answers a media id at once, and GET /v1/media/{id} (free) gives the image's URL when it is done
`POST /v1/media/video`	0.45 USDG	Priors 5-second video clip from a text prompt, or from an image Priors made (image_id), under strict content rules checked before payment (Higgsfield Kling 2.5 Turbo): answers a media id at once, and GET /v1/media/{id} (free) gives the clip's URL when it is done
`GET /v1/media/:id`	free	a media id's status, and when it is done its output URLs and when they expire
`GET /health`	free	status, snapshot block and age, payment settings and each route's price
`GET /openapi.json`	free	these routes as OpenAPI 3.1, each with its price
`GET /`	free	this page

Data comes from what Priors publishes: the snapshot of the pool (priors.trade/api/snapshot, at most about 30 seconds old), Score v2, the desk ledger, the stock vault's tokens and the owners' Ethos scores, each read at most once a minute. Every answer says which block it reflects in asOf. USDG amounts are decimal strings.

Every route checks its input and its data before it asks for payment: a malformed input is a 400, what Priors does not know a 404 (an agent not enrolled, an address with no agent, loan, deposit or stake, a stock the vault does not take, a backer that is not a pool root), and data that is not there a 503 with Retry-After. Nothing is charged for any of them.

POST /v1/screen and POST /v1/watch take a JSON body {"agents": [...]} with 1 to 50 entries: agent ids (integers or decimal strings), and for the screen also owner addresses. Each answer keeps the order given. A 404 means none of them is known.
GET /v1/pool/day?date=YYYY-MM-DD: one UTC day, from the pool's first day to today (today so far when no date is given).
GET /v1/stock-line/{symbol}?line=50: the line wanted in USDG. The answer gives the tokens it needs at the token's own loan-to-value (an agent's record bonus can add to it) and whether it fits now: the token open to new lines, at least the smallest loan (5 USDG), at most the vault's largest line, within the token's cap and the week's room.
GET /v1/credit/{agentId}?page=1: 100 loans a page, newest first, each with the transactions that prove it.
POST /v1/media/image takes {"prompt": "...", "aspect_ratio": "1:1"} (3 to 1000 characters; aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3) and POST /v1/media/video {"prompt": "...", "duration": 5, "image_id": "med_..."} (image_id optional: an image this API made, done, to start the clip from; no outside image or link in this version). Each answers a media id at once, with poll: read GET /v1/media/{id} (free) until status is completed, then output.urls; the files stay at least until output.expiresAt (7 days), so copy them if you need them longer. Images come from Higgsfield's Soul 2 (1080p), clips from Kling 2.5 Turbo.
Content rules, strict, checked before any payment: no real or named people (public figures, celebrities, politicians, anyone named), no nudity or sexual content, nothing involving children or minors, no violence or gore, no hate, no political campaigning, no other companies' logos, trademarks, brands or characters and no impersonation, no weapons or drugs. A prompt that breaks them is a 422 with the rule, and no offer; one the content check refuses after you signed is a 422 too, and the payment never settles. A generation the image service itself refuses or fails at once is not charged either; one that it refuses or fails later, after the payment settled, ends refused or failed in GET /v1/media/{id}, and is not refunded by itself.
The media routes stop at Priors' monthly limit: then they answer 503 with Retry-After (until the next month, UTC) before any offer, and nothing is charged. A busy image service is a 503 too.
Loan states: on-time, due-soon (within 24 hours), late (past due, inside the 3-day grace), defaultable (past the grace: anyone may mark it defaulted), defaulted, repaid, repaid-late. Verdicts, worst first: defaulted, late, frozen, borrowing, repaid, enrolled (no loan repaid yet), unknown.

A line backed by the stock vault (the agent's own stock tokens) carries collateral in the report: token, symbol, amount (in tokens), value (what the vault values them at, null while it will not), ltvBps, borrowRoom, hold (0, or why new loans wait: 1 a price jump, 2 a multiplier change, 3 a paused token, 4 a blocked vault), status and closing. Its available is the smaller of the pool's figure and borrowRoom. borrowRoom is 0, with refused saying why, when every loan would be refused whatever the vault's own figure: the agent changed hands since its position opened, defaulted, is frozen, or its owner has a default. Every other line has collateral: null. On any line, a default marked on the owner's account (on any of its agents) makes available 0 and adds ownerDefaulted: true: the pool lends to none of that owner's agents.

Payment

Scheme exact, network eip155:4663 (Robinhood Chain), asset USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals, EIP-3009 on the EIP-712 domain "Global Dollar" version 1.
Pay to 0x949206e4aF666C9FA5BfD527c7822358dB648Cf8, the amount of the route called (its 402 names it; a payment signed for another route's price is refused). Settled by the Priors facilitator; the settlement is an on-chain USDG transfer you can check.
Without payment the API answers 402 with a base64 PAYMENT-REQUIRED header. Decoded, for the report:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.priors.trade/v1/report/462",
    "description": "Priors credit report: identity, backer, line, available, record, score, open loans and recent history of one ERC-8004 agent, and the stock collateral behind a stock line",
    "mimeType": "application/json",
    "serviceName": "Priors"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:4663",
      "amount": "30000",
      "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
      "payTo": "0x949206e4aF666C9FA5BfD527c7822358dB648Cf8",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "Global Dollar",
        "version": "1"
      }
    }
  ]
}

Send the signed payment in PAYMENT-SIGNATURE, with the same request (for a POST, the same body). The API verifies it, builds the answer, settles, and returns 200 with a PAYMENT-RESPONSE header (the settlement: transaction hash, payer, network). If settlement fails you get a 402 and no data; if the answer cannot be built nothing is settled. Requests carrying a payment are limited per address: past the limit you get 429 with Retry-After, and nothing is charged.

Pay with @priors/x402

import { ethers } from "ethers";
import { createPayer, robinhood } from "@priors/x402";

const signer = new ethers.Wallet(process.env.AGENT_KEY, new ethers.JsonRpcProvider(robinhood.rpcUrl));
const { pay } = createPayer({ signer, maxPrice: "$0.10" }); // the dearest credit route (a video clip is 0.45); each call pays its own price
const { response } = await pay("https://api.priors.trade/v1/report/462");
console.log(await response.json());

It can also borrow the gap from the agent's own Priors line when its wallet is short (see the package README).

Pay with any x402 v2 client

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = x402Client.fromConfig({
  schemes: [{ network: "eip155:4663", client: new ExactEvmScheme(privateKeyToAccount(process.env.AGENT_KEY)) }],
  // USDG is not one of @x402's built-in assets: allow it, capped per payment (100000 = 0.10, the dearest credit route;
  // 450000 for a video clip)
  spendControls: { allowedAssets: [{ network: "eip155:4663", asset: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", maxAmountPerPayment: "100000" }] },
});
const paid = wrapFetchWithPayment(fetch, client);
const score = await paid("https://api.priors.trade/v1/score/462");
const screen = await paid("https://api.priors.trade/v1/screen", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ agents: [462, 7633] }) });

Why pay for this

A Priors score is earned by borrowing and repaying real USDG under a backer whose stake pays if the agent defaults. It cannot be bought or farmed, so it is a useful thing to check before you trust, pay or lend to an agent.