FastNear JS Agent-first NEAR RPC/API lib
HTTP payments New

Pay x402-protected URLs with NEAR.

x402 turns HTTP 402 Payment Required into a machine-payable flow: a server answers with a payment challenge, the client pays, and the same request retries with proof of payment. @fastnear/x402 implements the official x402 v2 exact scheme on near:mainnet and near:testnet — payments settle as NEP-141 fungible-token transfers authorized with a NEP-366 SignedDelegate, so a facilitator relays the transaction and pays gas on the payer's behalf. The package is package-only: it ships separately and is not part of near.js or agents.js.

Canonical payment shape
  • Protocol: x402 v2, exact scheme only, on near:mainnet and near:testnet.
  • Settlement: one NEP-141 ft_transfer (30 TGas, 1 yoctoNEAR deposit) relayed by the facilitator — native NEAR is not a direct payment asset, and recipients need token storage registration.
  • Authorization: the payer signs a NEP-366 SignedDelegate; wallet and local-key payers therefore need full-access keys.
  • Browser wallets must advertise both signDelegateActions and the timeout-aware signDelegateActionsWithTtl.
Integration map

Pick the smallest surface for the job.

Browser clients, Node clients, sellers, and facilitators use focused entrypoints so server code and secrets never leak into the wallet page.

Browser wallet payer

A user pays after clicking

Inject nearWallet into the x402 signer; the browser global is nearX402.

  • Import: @fastnear/x402 root
  • Factories: createFastNearWalletSigner, createNearPaymentFetch
  • Secrets: none in browser code
Node payer

A backend or agent pays

An RPC-backed local signer for server-side processes and AI agents paying protected URLs.

  • Import: @fastnear/x402/node + root
  • Factories: createLocalNearSigner, createNearPaymentFetch
  • Secrets: payer full-access key, server-side only
Seller

A server protects a route

Build the NEAR resource-server core, then hand it to the x402 HTTP framework adapter you choose.

  • Import: @fastnear/x402/server
  • Factory: createNearResourceServer
  • Secrets: usually none; the facilitator is configured explicitly — there is no default
Facilitator operator

A relayer verifies and settles

The relayer pays gas and the 1-yoctoNEAR deposit; HTTP framework and secret storage are operator choices.

  • Import: @fastnear/x402/facilitator
  • Factory: createNearFacilitator
  • Secrets: relayer full-access key, server-side only
Quickstarts

Two payer paths, one paid-fetch helper.

Both paths end in createNearPaymentFetch: a drop-in fetch that answers a 402 challenge by paying, then retries the request. The seller quickstart and the full facilitator surface live in the x402 key of recipes.json.

Browser wallet payer

IIFE globals from wallet.js and x402.js. Connect and pay must be explicit user actions — never auto-connect or auto-pay. 

<script src="https://js.fastnear.com/wallet.js"></script>
<script src="https://js.fastnear.com/x402.js"></script>
<script type="module">
  // Wire these to buttons: connect first, pay second.
  await nearWallet.connect();

  const signer = nearX402.createFastNearWalletSigner({
    wallet: nearWallet,
  });

  const paidFetch = nearX402.createNearPaymentFetch({
    signer,
    network: "near:testnet",
  });

  const response = await paidFetch("https://seller.example.com/paid");
</script>
Node payer

The quickstart from the catalog (ESM). The payer secret key stays in server-side environment variables, never browser code. 

import { createNearPaymentFetch } from "@fastnear/x402";
import { createLocalNearSigner } from "@fastnear/x402/node";

const { NEAR_PAYER_ACCOUNT_ID, NEAR_PAYER_SECRET_KEY, X402_RESOURCE_URL } = process.env;
if (!NEAR_PAYER_ACCOUNT_ID || !NEAR_PAYER_SECRET_KEY || !X402_RESOURCE_URL) {
  throw new Error("NEAR_PAYER_ACCOUNT_ID, NEAR_PAYER_SECRET_KEY, and X402_RESOURCE_URL are required");
}

const signer = createLocalNearSigner({
  accountId: NEAR_PAYER_ACCOUNT_ID,
  secretKey: NEAR_PAYER_SECRET_KEY,
  rpcUrls: { "near:testnet": "https://rpc.testnet.fastnear.com" },
});
const paidFetch = createNearPaymentFetch({ signer, network: "near:testnet" });
const response = await paidFetch(X402_RESOURCE_URL);
if (!response.ok) throw new Error(`Paid request failed: ${response.status}`);
console.log(await response.json());
Wallet compatibility

The browser path is stable with tested Meteor Wallet support; other wallets must advertise both timeout-aware delegate-signing capabilities (signDelegateActions and signDelegateActionsWithTtl) and pass the x402 testnet harness before being documented as compatible.

Guardrails

Hard constraints and safe defaults.

These rules come from the machine-readable catalog — agents and humans should apply the same ones.

Hard constraints
  • Only x402 v2 exact payments on near:mainnet and near:testnet are supported.
  • Payments use NEP-141 tokens; native NEAR is not a direct payment asset.
  • Wallet and local-key payers require full-access keys, and recipients need token storage registration.
  • Resource servers require an explicit facilitator; no x402.org or other default is selected.
  • Browser wallet access is injected explicitly, and payment occurs only when the application calls the paid-fetch function.
Safe defaults
  • Pin near:testnet during development and a concrete NEAR network in production; use near:* only for an intentionally cross-network client.
  • Keep payer and relayer secret keys in server-side secret storage, never browser code.
  • String and number seller prices use the official USDC contract; wNEAR and custom tokens require an explicit { amount, asset } price.
  • Always configure a facilitator explicitly.
Go deeper

AI agents: read the x402 key in recipes.json and the x402 section of llms.txt before editing an app. Humans: the canonical package guide is the @fastnear/x402 README, and the facilitator directory lives at docs.x402.org.