@priors/x402
v0.8.9
Published
x402 v2 on Robinhood Chain (eip155:4663) in USDG: a money parser for ExactEvmScheme, the Priors facilitator config, and a payer that borrows the gap from a Priors credit line.
Downloads
3,550
Maintainers
Readme
@priors/x402
x402 on Robinhood Chain (eip155:4663) in USDG, on top of the official @x402/* 2.27 packages, plus credit:
when an agent is short, it can borrow the gap from its Priors line.
registerUsdg(scheme):price: "$0.05"oneip155:4663means USDG (6 decimals, EIP-712 domain "Global Dollar" v1).priorsFacilitator({ apiKey }): config for the officialHTTPFacilitatorClient, pointed athttps://facilitator.priors.trade, with your merchant key asAuthorization: Bearer …on verify/settle/supported.createPayer({ signer, … }).pay(url, init): a fetch that pays x402 USDG (v2, and legacy v1robinhoodbodies) and borrows the gap when you allow it.robinhood: the constants (network and its legacy v1 name, chain id, USDG address and decimals, EIP-712 domain, facilitator URL, public RPC URL, Priors pool, lens, identity registry and stock vault addresses).@priors/x402/check: refuse a payer with a bad Priors record in one line, in front of any x402 paywall (Express, Hono, Cloudflare Workers).
npm i @priors/x402 @x402/core @x402/evm ethersThe examples below also use optional packages: @x402/express (Express), @x402/hono (Hono), and @x402/mcp with
@modelcontextprotocol/sdk (the paid MCP tool). Install the ones you use.
Merchant: Express
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { registerUsdg, priorsFacilitator, robinhood } from "@priors/x402";
const server = new x402ResourceServer(new HTTPFacilitatorClient(priorsFacilitator({ apiKey: process.env.PRIORS_MERCHANT_KEY })))
.register(robinhood.network, registerUsdg(new ExactEvmScheme()));
const app = express();
app.use(paymentMiddleware({
"GET /report": {
accepts: { scheme: "exact", price: "$0.05", network: robinhood.network, payTo: "0xYourAddress" },
description: "One report, 0.05 USDG",
},
}, server));
app.get("/report", (req, res) => res.json({ report: "…" }));
app.listen(3000);The merchant key comes from registering your payTo with the facilitator (POST /merchants/register, or the
merchant page of x402.priors.trade). createResourceServer({ apiKey }) does the first two lines in one call.
On USDG, a facilitator's success, or a transaction's status, is not proof of payment. USDG does not revert a transfer
on an authorization already used or cancelled: the transaction succeeds and moves nothing, and a payer can cancel its
authorization between the facilitator's verify and its settle. The Priors facilitator decides by USDG's own logs. To
check them on your side too (another facilitator, or defense in depth), pass confirm: true (or { rpcUrl }) to
createResourceServer: a settlement whose receipt has no USDG
AuthorizationUsed followed by its Transfer to your payTo answers settlement_moved_nothing, and the paid response
is withheld. If the receipt can't be read within waitMs (3 s; every read ends by then, so a node that hangs holds the
response no longer), the facilitator's answer stands.
Merchant: Hono
import { Hono } from "hono";
import { paymentMiddleware } from "@x402/hono";
import { createResourceServer, robinhood } from "@priors/x402";
const app = new Hono();
app.use(paymentMiddleware({
"GET /report": {
accepts: { scheme: "exact", price: "$0.05", network: robinhood.network, payTo: "0xYourAddress" },
description: "One report, 0.05 USDG",
},
}, createResourceServer({ apiKey: process.env.PRIORS_MERCHANT_KEY })));
app.get("/report", (c) => c.json({ report: "…" }));
export default app;Merchant: a paid MCP tool (@x402/mcp)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createPaymentWrapper } from "@x402/mcp";
import { createResourceServer, robinhood } from "@priors/x402";
const resourceServer = createResourceServer({ apiKey: process.env.PRIORS_MERCHANT_KEY });
await resourceServer.initialize();
const accepts = await resourceServer.buildPaymentRequirements({
scheme: "exact", network: robinhood.network, payTo: "0xYourAddress", price: "$0.01",
});
const paid = createPaymentWrapper(resourceServer, { accepts });
const mcp = new McpServer({ name: "my-paid-tools", version: "1.0.0" });
mcp.tool("quote", "A price quote. Costs 0.01 USDG.", {}, paid(async () => ({ content: [{ type: "text", text: "42" }] })));
await mcp.connect(new StdioServerTransport());An agent pays it with @x402/mcp's client and this package's USDG client:
wrapMCPClientWithPayment(mcpClient, createUsdgClient({ signer, maxPrice: "$0.05" }), { autoPayment: true }).
Refuse a bad payer in one line
@priors/x402/check (0.7.0) puts the payer's Priors record check in front of whatever runs your x402 paywall:
@x402/express, @x402/hono, a legacy v1 stack, your own. It reads the payer from the payment header (v2
PAYMENT-SIGNATURE, v1 X-PAYMENT), reads its record (https://priors.trade/api/check, cached as recordGate
caches it) and judges it with the same policy as recordGate:
- no payment header: the request goes on untouched, and the paywall answers 402 as before;
- a payer the policy refuses:
403with{ "error": "priors_payer_defaulted", "message": "…" }(orpriors_record_too_short,priors_score_too_low;priors_payer_unknownfor a header that names no single payer). The paywall never sees the payment, so it is never verified or settled: no money moves; - a record that cannot be read:
503withRetry-After, the same JSON withpriors_record_unavailable. It fails closed;failOpen: trueserves instead. That includes an HTTP 200 from the record service that is not a record answer (noagentslist, anerror); only an answer's ownagents: []is a payer Priors does not know (0.7.1).
Express (and Connect, or a bare node:http server: check(req, res, next)):
import { requireRecord } from "@priors/x402/check";
app.use(requireRecord({ minRepaid: 1 })); // first: the record check
app.use(paymentMiddleware(routes, server)); // then the paywall, as in "Merchant: Express"Hono:
import { honoRecord } from "@priors/x402/check";
app.use(honoRecord({ minRepaid: 1 })); // first: the record check
app.use(paymentMiddleware(routes, server)); // then the paywall, as in "Merchant: Hono"Cloudflare Workers, or any fetch handler (Next route handlers, Bun): wrap the handler that holds the paywall, so the
check runs before it.
import { withRecord } from "@priors/x402/check";
const app = new Hono();
app.use(paymentMiddleware(routes, server)); // the paywall, inside app.fetch
app.get("/report", (c) => c.json({ report: "…" }));
export default { fetch: withRecord(app.fetch, { minRepaid: 1 }) }; // runs before app.fetchElsewhere (Fastify, Koa, a router of your own), await checkRequest(request, opts) gives the decision: { ok, payer,
record, reason, message, status, retryAfter }; reuse the same opts object to keep one cache.
Why it is safe before the paywall. The check runs before the x402 middleware, so the header it reads is not
verified yet, and anyone can write any address in it. The check can only say no. A forged payer gets the forger
refused, or goes on to the paywall, which verifies the signature: a payment from an address the sender cannot sign for
fails there, as it would without the check. Two headers that could make the check judge one address while another pays
are refused, not passed (priors_payer_unknown): a payment naming both EIP-3009 and Permit2 arms (GHSA-6vjc), and a v2
and a v1 header naming different payers. So is a header that does not decode. Put it after the paywall instead and a
refused payer would already have paid.
Options: refuseDefaulted (default true), minRepaid, minScore, source, rpc, pool, checkUrl,
cacheSeconds, cacheMax and fetchImpl, as for recordGate below (with source: "chain" the payer names its agent
in X-Priors-Agent); failOpen (default false), retryAfter (seconds, default 10) and onDecision (called with
the decision for each request carrying a payment). Prices by record stay with recordGate's tierPrice(): they depend
on the amount the payment carries, which the paywall reads.
A runnable demo, on node:http alone: examples/check-record.
Merchant: check who is paying (record gate)
The payer's Priors record is what it has borrowed and repaid on Robinhood Chain, and whether it ever defaulted.
recordGate reads it before the facilitator sees the payment, inside an x402ResourceServer from @x402/core
(createResourceServer); on any other stack, use @priors/x402/check above. A payment the merchant's policy refuses
is never verified or settled: no money moves, and the client gets the usual 402 with the reason
(priors_payer_defaulted, priors_record_too_short, priors_score_too_low, priors_price_not_entitled,
priors_record_unavailable).
import { createResourceServer, recordGate } from "@priors/x402";
const server = createResourceServer({ apiKey: process.env.PRIORS_FACILITATOR_KEY });
recordGate({ refuseDefaulted: true, minRepaid: 1 }).attach(server); // then paymentMiddleware(routes, server) as above| option | default | |
|---|---|---|
| refuseDefaulted | true | refuse a payer whose agent defaulted on a Priors loan |
| minRepaid | 0 | repaid Priors loans the payer must have |
| minScore | none | Priors Score v2 the payer must have (on-chain score with source: "chain") |
| source | "api" | "api": https://priors.trade/api/check by the payer's address (every agent it owns or declared as its payment wallet; no key). "chain": Priors pool v2 read over rpc, for the agent the payer names in the X-Priors-Agent header, after checking the paying address controls it; a payer the pool marked for a default (or the named agent's owner, if marked) counts as defaulted whatever agent it names, or none. Use it on a fork, or to depend on no Priors service |
| rpc, pool | public RPC, the published pool | for source: "chain" |
| tiers, basePrice | none | prices by record: tiers: [{ minRepaid: 3, price: "$0.01" }], basePrice: "$0.02" |
| cacheSeconds | 60 | how long a payer's record is reused |
| cacheMax | 10000 | (0.6.4) at most this many records kept; then the expired ones go, then the oldest. With source: "api" the record is keyed by the payer only, so X-Priors-Agent adds no entry |
| onDecision | none | called with { payer, record, ok, reason } for each payment |
A record that cannot be read refuses rather than serves on a guess: the check API down, or answering HTTP 200 without a
record list (0.7.1); with source: "chain", a failed read of the pool or of the named agent's owner.
Prices by record. Give the route price: gate.tierPrice(). A client states its address in X-Payer (and its
agent in X-Priors-Agent with source: "chain") to be quoted its tier. That statement is only a request: when the
payment arrives, the gate reads the record of the address that actually signed it. It refuses a payment below that
payer's own price, so claiming someone else's record gets nothing.
const gate = recordGate({ basePrice: "$0.02", tiers: [{ minRepaid: 3, price: "$0.01" }] });
gate.attach(server); // attach returns the server; tierPrice is on the gate
// routes: { "GET /report": { accepts: { scheme: "exact", price: gate.tierPrice(), network: "eip155:4663", payTo } } }Agent: pay, and borrow the gap
import { ethers } from "ethers";
import { createPayer, robinhood } from "@priors/x402";
const provider = new ethers.JsonRpcProvider(robinhood.rpcUrl);
const signer = new ethers.Wallet(process.env.AGENT_KEY, provider); // the agent's wallet (and its Priors controller)
const payer = createPayer({
signer,
maxPrice: "$0.10", // most one call may cost; a dearer 402 is refused before anything is signed
// optional credit: borrow what the wallet is short of, from the agent's Priors line
pool: robinhood.pool, agentId: 1234, maxBorrow: "$5",
});
const { response, paid, borrowed, loanId, dueAt } = await payer.pay("https://api.example.com/report");
console.log(response.status, await response.json(), { paid, borrowed, loanId, dueAt });
// once the agent has been paid by its client:
const { open } = await payer.settleLoans(); // repays open loans, earliest due first, as far as the wallet covers; before dueAt. `open` lists what it could not payAmounts: a bigint or integer is atomic USDG (6 decimals: 100000n = $0.10); a string with $ is dollars.
A result also carries the requirement it paid, its x402Version and, on success, the decoded settlement
(PAYMENT-RESPONSE) when the merchant sent one. Other createPayer options: maxValiditySeconds (at most 600, the
default), asset (a USDG address for a fork or test token; default the pool's usdg(), else mainnet USDG),
fetchImpl, pendingRetries (default 6), maxSleepMs (longest wait between resends, default 30 s) and sleep.
What pay() promises (the rules of sdk/float.mjs, unchanged)
maxPrice(default $0.10) is checked before anything is read, signed or borrowed.- Borrowing happens only when the wallet is short, a
poolandagentIdare given, and the price is withinmaxBorrow(default 0: never), and only for a requirement x402 core will sign: apaymentFlowcore does not know is skipped for a later requirement, and core's own selection takes the one picked before the balance is read, topped up or borrowed against (NO_USDG_REQUIREMENTotherwise). It drawsmax(shortfall, pool minimum loan), refuses abovemaxBorrowor the pool'smaxLoan, caps the fee at the pool's quote (ormaxFee), and simulates the borrow first. A borrow that was sent and whose answer was lost (the broadcast's or the receipt's) may have mined: it throwsBORROW_UNCONFIRMEDwithborrowedset,loanId: null,unconfirmed: trueand the txhashwhen known. Count it, check the agent's loans, and repay before the due date. From 0.8.2 the node's "insufficient funds" for a borrow it already holds is one too: ethers sends a request again after an HTTP 429, and a node that took the first copy refuses the identical bytes that way (GHSA-rh27-m4c4-p2c7).INSUFFICIENT_FUNDSis thrown as is only for a borrow the node does not know, asked by its hash; a lookup that fails counts as sent. - Term: 7 days by default, clamped into the pool's range; an explicit
termSecondsabove the pool's maximum is refused. The result'sdueAtis when the loan is due; three days later anyone can mark it defaulted, and the agent's record is burnt. - Authorization window: at most 600 s, whatever
maxTimeoutSecondsthe merchant asks. The payload'sacceptedstays the merchant's requirement verbatim. - One signature per purchase. While the merchant answers "pending" (v2
settlement_pending, or a legacy{pending:true}body) the same signed payment is resent, up to 6 times, honouringRetry-After. If it is still pending, the result is{ pending: true, paymentHeaders }: callpayer.resend(url, paymentHeaders)later, and do not callpay()again for the same purchase. A payer also remembers its unsettled payments: a laterpay()for the same purchase (the method; the URL as the merchant reads it: without its fragment, query fields in name order,+and%20alike, escapes in one case; and the body: a JSON body by its value, so key order, whitespace and how a number is written do not count, and a urlencoded or multipart form by its fields;purchaseKey(request)gives it) resends that one (resent: true) until it expires, plusSKEW_SECONDS(60 s, exported) for a chain clock behind this machine's. That memory is per payer and per process: passonSigned(s)tocreatePayerto record each payment before it leaves (s.paymentHeaders,s.validBefore,s.price,s.purchase), so a new process can resend it instead of signing again. IfonSignedthrows, the payment is not sent:pay()rejects withNOT_RECORDEDand nothing can be settled.@priors/mcpdoes this with a state file. - Legacy v1 402 bodies (
network: "robinhood",X-PAYMENT) are paid the waysdk/float.mjspays them. - No redirects. Requests go out with
redirect: "manual"unless you pass anotherredirectininit(redirect: undefinedcounts as none): a signed payment never travels to a host you did not name, and a 3xx comes back as the answer. - Bounded. Bodies are read up to 256 KB (
readCapped).timeoutMs(60 s by default; 0 = none) bounds each request,signalevery call andinit.signal(asfetchtakes it) the one call: once either has fired, nothing more is read, topped up, borrowed or signed, andpay()rejects with the abort. A timeout or an abort once the payment is out returns{ pending: true, timedOut: true, paymentHeaders }, and a dropped connection{ pending: true, transportError: true, error, paymentHeaders }: never an error once the payment may be out. An error thrown after a loan or a signature carriesborrowed,loanId,dueAtandsigned. - One payment at a time per payer: two concurrent
pay()calls on a short wallet do not both borrow the gap. signed: every result of a signed payment carriessigned: { paymentHeaders, validBefore }. UntilvalidBeforethe merchant can still cash it, so a retry of the same purchase mustresendthese headers.
Refusals throw a PayError with a code: PRICE_ABOVE_MAX_PRICE, PRICE_ABOVE_MAX_BORROW,
MIN_LOAN_ABOVE_MAX_BORROW, ABOVE_MAX_LOAN, TERM_OUT_OF_RANGE, FEE_TOO_HIGH, NO_POOL, NO_USDG_REQUIREMENT
(no requirement this payer signs: USDG on Robinhood Chain, or USDC on Base when enabled; from 0.8.2 its message says
when the 402 asks for USDG by Permit2, which this payer does not sign), BAD_402,
BORROW_WOULD_REVERT, BORROW_UNCONFIRMED (not a refusal: the borrow was sent, and may have opened a loan),
NO_SIGNER, NO_PROVIDER (also: networks names Base and no baseProvider was given), NO_FETCH,
UNSUPPORTED_TRANSFER_METHOD (a requirement that is not EIP-3009), BAD_NETWORK (a networks entry not in the
allowlist), BASE_FLOAT_SHORT (a Base requirement, and the wallet's USDC on Base, less what baseReserve() keeps
back, is short of the price: nothing was signed; price, balance, reserve, network and asset on the error),
NOT_CONTROLLER (repayLoan, settleLoans), NOT_OWNERS_LOAN (repayLoan, 0.6.3), NOT_AGENTS_WALLET (repayLoan,
settleLoans, borrowGap, borrowLine, 0.8.1). The
bridge and payViaGateway (below) add their own codes. The credit helpers add
LOAN_SIZE_OUT_OF_RANGE (quoteBorrow, borrowLine), LOAN_NOT_ACTIVE, INSUFFICIENT_USDG, REPAY_WOULD_REVERT
(repayLoan) and NO_STOCK_VAULT (stockPosition, stockAssets).
Why pay() is not just @x402/fetch's wrapFetchWithPayment
It uses the same parts (x402Client, x402HTTPClient, ExactEvmScheme), but writes the request loop out, because
the wrapper (2.27) cannot keep the rules above: it can only act inside payload creation, so a borrow refusal would
surface as a generic "Failed to create payment payload" error; when a response hook reports recovered it signs a
fresh payload while the first may still settle (two payments for one call); it has no pending loop and never hands
back the signed header; and it cannot route v1 robinhood bodies. If you never borrow, createUsdgClient() gives you
an x402Client with the same USDG allowance, price cap and 600 s window for wrapFetchWithPayment:
import { wrapFetchWithPayment } from "@x402/fetch";
import { createUsdgClient } from "@priors/x402";
const fetchWithPay = wrapFetchWithPayment(fetch, createUsdgClient({ signer, maxPrice: "$0.10" }));Credit helpers
@priors/x402/credit has the Priors v2 pieces the MCP server uses: creditContracts, creditStatus, quoteBorrow,
borrowLine, repayLoan, settleLoans, balances, borrowGap, plus poolContract, explainRevert (a revert as
Name(args)), (0.8.2) refusedUnsent and refusedTxHash (whether a failed broadcast sent nothing, by the hash of
its signed bytes), LOAN_STATUS and the ABIs (POOL_ABI, LENS_ABI, ERC20_ABI, STOCK_VAULT_ABI). repayLoan pays
only a loan of an agent the signer controls (owner or pool delegate) or is the declared ERC-8004 wallet of (whether or
not the pool names it the delegate: an agent whose delegate is LineKey, the spending key, is repaid from its own key;
GHSA-45h8-v5q8-4j43, settleLoans too); any other loan is refused with NOT_CONTROLLER before anything is sent.
From 0.6.3 it also pays only a loan the agent's owner now took: a loan opened while someone
else held the agent (Loan.owner is another address) is refused with NOT_OWNERS_LOAN, and settleLoans leaves such
loans in open and lists them in others with who opened them (GHSA-mmp8).
From 0.8.1, and breaking for a delegate-only key: borrowing and repaying both need the signer to be the agent's
current owner or its declared ERC-8004 wallet (getAgentWallet). The pool lets an owner name any address its delegate
with no word from that address, so a delegate that is not the declared wallet is refused with NOT_AGENTS_WALLET
before anything is read or sent — in repayLoan and settleLoans, and equally in borrowGap and borrowLine, so
that no key can draw a loan this package would then refuse to repay. The owner declares the agent's key once: the key
signs AgentWalletSet (priors-mcp link-wallet) and the owner sends the registry's setAgentWallet.
Stock lines (the Priors stock vault, robinhood.stockVault, backs a line with the agent's own stock tokens;
creditContracts reads it unless addresses.stockVault says otherwise): creditStatus carries collateral {
token, amount, value (what the vault prices them at, null while it will not), ltvBps, borrowRoom, hold
(0, or why new loans wait: STOCK_HOLDS), holdReason, status, closing } for a stock line (null for any other),
and its available is the smaller of the pool's figure and borrowRoom (stockCollateral(c, id, sponsor) reads that
object on its own). From 0.8.3 (GHSA-qcrq-x8xg-25vg) available and borrowRoom are 0, and refused says why, when
no loan can be drawn whatever the vault's or the lens's figure: the agent defaulted or is frozen, its owner can't be
read, it changed hands since its stock position opened (the vault lends only to the owner who opened it), or a default
is marked on its owner's account (the pool's ownerDefaults, a custodian's skipped), this last on every line.
stockPosition(c, id, assets?) and
stockAssets(c, assets) read one position and the accepted tokens (price, whether the vault lends now, LTV).
Savings (@priors/x402/savings)
An agent's spare USDG in a Morpho vault (Morpho Vault V2, ERC-4626; Steakhouse USDG by default), taken back out when it has to pay or repay:
import { savingsContracts, savingsOf, save, unsave, topUpFromSavings } from "@priors/x402/savings";
const c = await savingsContracts({ runner: provider }); // refused unless there is a contract whose asset is USDG
await save(c, signer, 20_000_000n); // 20 USDG in (checks the deposit gate first)
const s = await savingsOf(c, signer.address); // { saved, withdrawable, reachable, wallet, shares, ... }
await unsave(c, signer, { all: true });
// pay and repay from savings before borrowing
const payer = createPayer({ signer, pool: robinhood.pool, agentId, maxBorrow: "$1", topUp: (need) => topUpFromSavings(c, signer, need) });
const r = await payer.pay(url); // r.savings: what the top-up did
const { open } = await payer.settleLoans(); // tops up to what all open loans need first; check `open`withdrawableis what a plain withdrawal pays now (idle, then the vault's liquidity market), found by simulating it (Morpho Vault V2 answers 0 tomaxWithdrawby design).reachableadds the in-kind exit:unsaveandtopUpFromSavingsmove money out of the vault's other penalty-free markets and withdraw it in one transaction (forceDeallocate+withdrawinmulticall) when the plain path falls short.- Every vault transaction is sent with a gas margin. Refused before any transaction:
SHORT,ZERO,NOTHING_SAVED,MORE_THAN_SAVED(each deposit is worth one base unit less than paid in),VAULT_ILLIQUID(withwithdrawableandreachable),EXIT_FAILED,EXIT_BLOCKED,DEPOSITS_CLOSED,NO_GAS,BAD_VAULT,NOT_USDG.VAULT_FULLcomes after the approval, which is then put back (allowanceReset). After sending:REVERTED(on chain) andUNCONFIRMED(sent, confirmation not read; check before retrying), both with thehash; (0.8.2) the node's "insufficient funds" for a transaction it already holds isUNCONFIRMEDtoo, notNO_GAS. A node failure is thrown as is. - The in-kind exit uses only markets other than the liquidity market, with a penalty of 0, charged to an address that holds nothing: a penalty switched on before the transaction lands makes it revert rather than cost the saver.
- Every function takes an optional
{ signal, sent }: the signal stops it before it sends a transaction, andsentis the hash once one is sent. AtopUpwhose error haspending: true(or codeUNCONFIRMED) makespaystop withSAVINGS_PENDINGbefore any loan or signature. - The money is the agent's own and the vault's risks are the agent's; Priors never holds it.
Autopay (@priors/x402/autopay)
The agent's own wallet repays its loans on time through AutoRepay v2:
it approves a budget and enrolls once, and Priors' keeper (or anyone) repays each loan in the 6 hours before it is due,
from that wallet, while it holds enough. AutoRepay has no owner and no upgrade; it sends the wallet's USDG only to the
pool, for the agent's own loans. A plan lasts while the agent keeps the owner and the wallet it was set under: after a
new key or a sale, autopayStatus says stale and autopayOn is needed again. From 0.5.0 autopayOn refuses
AutoRepay v1 (retired before use) with AUTOREPAY_V1. The wallet must be a key of the agent's own, declared with the
registry's setAgentWallet, not the owner's address: an agent whose declared wallet is its owner (what register()
leaves) is repaid by AutoRepay under its owner's plan only, so autopayOn refuses it with OWNER_IS_WALLET and
autopayStatus answers ownerIsWallet: true (since the version after 0.8.5).
import { autopayContracts, autopayOn, autopayStatus, autopayOff, defaultCap } from "@priors/x402/autopay";
const c = autopayContracts({ runner: provider, address: AUTOREPAY, registry, usdg, savingsVault, pool });
await autopayOn(c, wallet, agentId, { cap: defaultCap(line) }); // approves 4 x cap, then enroll(agentId, cap, false, true)
const st = await autopayStatus(c, wallet.address, agentId); // plan, budget, next loan and its window, shortfallcreatePayer({ reserve }): a payment that would cut into whatreserve()returns (e.g.autopayReserve(status), what loans whose window opens in the next 24 h pull) is refused withRESERVEbefore anything is signed or borrowed.settleLoans({ onlyInWindow: true })(andpayer.settleLoans({ onlyInWindow: true })): repay only the loans whose window (repayWindow, AutoRepay's own rule, never in a loan's first hour) is open, or that are past due; the others come back inwaiting.
SeatVaultV5 lines (@priors/x402/credit)
A line backed by SeatVaultV5 has no room until it is refreshed: V5 vouches nothing at the open and raises the pool's
vouch only on refresh, by the agent's owner or by the agent's pool delegate that V5 recorded (noteDelegate) at least
24 hours before. With createPayer({ v5, v5Root }) (and creditContracts({ addresses: { seatVaultV5,
seatVaultV5AgentId } }) for borrowLine), a borrow on such a line first calls v5BeforeBorrow: the owner, or a key
V5 recorded a day ago, refreshes the line. V5 lends for at most 10 days: from 0.8.3 v5BeforeBorrow takes the loan's
term (required on a V5 line, V5_TERM_REQUIRED without it) and refuses a longer one with V5_TERM_TOO_LONG before
anything is sent (GHSA-xccq-5ghg-w7mq). V5 also lends to no caller but the owner until 24 hours after it recorded that
key, whatever the line's room: a key V5 has not recorded is recorded now, and it, or one recorded under 24 hours ago,
stops with V5_DELEGATE_WAIT, saying when it can borrow (readyAt; the owner can borrow from Go mode meanwhile, which
refreshes first).
Paying USDC sellers on Base (networks, @priors/x402/bridge)
From 0.6.0, and off unless you ask for it. Many x402 sellers take USDC on Base only. A payer can pay them from a small USDC balance the agent keeps on Base, its Base float, while the loan and its repayment stay in USDG on Robinhood Chain.
import { ethers } from "ethers";
import { createPayer, BASE_USDC } from "@priors/x402";
import { fundBase, returnToRobinhood } from "@priors/x402/bridge";
const base = new ethers.JsonRpcProvider(BASE_USDC.rpcUrl);
const payer = createPayer({ signer, networks: ["eip155:4663", "eip155:8453"], baseProvider: base, maxPrice: "$0.10" });
await fundBase({ signer, amount: 5_000_000n }); // 5 USDG on Robinhood Chain -> about 4.99 USDC on Base (Across)
await payer.pay("https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools"); // a seller paid in USDC on Base
await returnToRobinhood({ signer, amount: 1_000_000n, baseProvider: base }); // USDC back to USDG (Relay, no gas on Base)- The allowlist (
NETWORKS, frozen): USDG oneip155:4663("Global Dollar"/"1") and USDC oneip155:8453(0x833589fC…2913, "USD Coin"/"2"), matched by full address only.pickV2Requirement(accepts, asset, { networks })refuses any other token, a lookalike (two "USDG" tokens on Robinhood Chain copy USDG's address prefix and suffix), and any EIP-712 domain but the token's own; a seller that takes both is paid on Robinhood Chain. Legacy v1 bodies stay Robinhood Chain only.createUsdgClient({ networks })registers Base only when it is named. - Paying on Base reads the wallet's USDC through
baseProviderand never borrows, tops up from savings or reads the Autopay reserve (those are Robinhood Chain's): a float short of the price isBASE_FLOAT_SHORT, before anything is signed.baseReserve: () => bigintnames what the float keeps back (read before the balance;@priors/mcpkeeps back areturnToRobinhoodwhose authorization can still be used): the price must fit in the rest.onSignedand the result carrynetworkandasset. fundBase({ signer, amount, maxFeeBps?, timeoutMs?, onDepositSending? }): Across. The quote (acrossQuote,checkAcrossQuote) is refused unless its tokens, chains and both spokes are the pinned ones (ACROSS), the amount is above Across's minimum, the quote is fresh enough for the spoke and the fee is withinmaxFeeBps(default 100). Then an approval of exactly the amount (only when the allowance is short), a simulateddepositV3to the signer's own address on Base with the quote'soutputAmountexactly,onDepositSendingawaited before the broadcast, and Across's deposit status polled until it is filled. Needs ETH for gas on Robinhood Chain.returnToRobinhood({ signer, amount, baseProvider?, maxFeeBps? }): Relay's gasless route. Relay's quote carries an EIP-712ReceiveWithAuthorization; it is never signed as returned.checkRelayReturnchecks every field (USDC's domain on Base, from the signer, to Relay's pinned proxyRELAY.receiver, the exact value, valid from now for at most 15 minutes, a 32-byte nonce, USDG on Robinhood Chain by full address as the output, the signer as recipient, the fee) and the message signed is rebuilt from those values. It never goes throughCappedExactEvmScheme.submitRelayPermithands it to Relay as Relay's own SDK does; that call is unverified against the live API until the first real return.- Errors (
PayError,movedsays whether money may have left): before anything is sent,BRIDGE_QUOTE_FAILED,BRIDGE_QUOTE_REFUSED,BRIDGE_FEE_TOO_HIGH,INSUFFICIENT_USDG,BRIDGE_WOULD_REVERT,BRIDGE_REVERTED,NO_GAS,NOT_RECORDED,RELAY_QUOTE_FAILED,RELAY_QUOTE_REFUSED,INSUFFICIENT_USDC; once it may be out,DEPOSIT_UNCONFIRMED(the deposit's answer was lost; from 0.8.2 also the node's "insufficient funds" for a deposit it already holds),BRIDGE_PENDING(not filled in the time: it may still land, or Across refunds it on Robinhood Chain after its fill deadline),BRIDGE_REFUNDED,RETURN_PENDINGandRETURN_FAILED(the authorization is out until it expires). Never send a transfer again while one may be out.
Sellers through the Vantis gateway (payViaGateway)
Since 0.8.0. Off unless you ask for it. Vantis' Keyring gateway
(https://keyring.vantis.sh/gateway) sells calls to the x402 services in its catalog, most of them paid in USDC on Base,
for one USDG price on Robinhood Chain. Keyring pays the seller itself and relays the answer. A payer with a gateway
buys through it with its usual USDG payment, so the agent's Priors line can cover a Base seller with no Base float.
const payer = createPayer({ signer, pool: robinhood.pool, agentId: 1234, maxBorrow: "$5", maxPrice: "$0.10",
gateway: {} }); // {} = https://keyring.vantis.sh, maxFeeBps 1000
const r = await payer.payViaGateway({ resource: "https://stableenrich.dev/api/exa/search", method: "POST", input: { query: "x402" } });
// or { serviceId: "svc_81fe57c734", input }; r.gateway = { serviceId, resource, method, network, listed, quoted }Before anything is signed or borrowed:
- The seller's record is read from Keyring. It must name the
resource(andmethod) you asked for. Keyring'ssuspiciousandtestnetflags, and a record with no listed price, are refused. - Keyring's quote must come from an armed gateway for an available seller, in USDG on Robinhood Chain. It must be
at most
maxPriceand at mostmaxFeeBpsover the seller's own listed price. - The 402 of
POST /x402/runmust ask no more than the quote, in USDG on Robinhood Chain only (never Base, even withnetworksnaming Base). Withgateway.payToset, it must pay that address.
Then it is paid as pay() pays any Robinhood Chain merchant: from the balance, then topUp, then a loan of only the
shortfall within maxBorrow, with one signature. gateway.url must be https.
Not yet seen live: the 402's exact shape (v2 or v1; the payer pays either), Keyring's payTo, and how input maps
onto each seller's request. Make one small live call before relying on it, then pin gateway.payTo. Codes:
GATEWAY_OFF,BAD_GATEWAY,BAD_GATEWAY_SERVICE;GATEWAY_NO_SERVICE,GATEWAY_REFUSED,GATEWAY_UNAVAILABLE;GATEWAY_FEE_TOO_HIGH,GATEWAY_PRICE_ABOVE_QUOTE,GATEWAY_PAYTO_MISMATCH.
Which route to use when, and Dexter as a merchant's facilitator: docs/X402-ROUTES.md in the repository.
Tests
npm run test:packages in the Priors repository: unit tests with mocks, and, with RPC_URL set, an anvil fork of
chain 4663 where a standard @x402/express server priced with registerUsdg is paid by createPayer.
scripts/test-x402-check.mjs (part of npm test) runs @priors/x402/check through Express (alone and in front of
@x402/express), Hono and a fetch handler, and scripts/demo-x402-check.mjs runs the demo from the packed tarball
against the live check API. scripts/test-x402-base.mjs (also part of npm test) covers the Base path and the
bridge; with --fork, BASE_RPC_URL settles a seller's USDC 402 on a Base fork, and RPC_URL deposits into the real Across spoke on a
Robinhood Chain fork. scripts/test-x402-routes.mjs (part of npm test) runs payViaGateway against a mock Keyring
and a mock Base seller, and pays 4663 merchants whose facilitator is a mock of Dexter's.
