SDK

The SDK lets an x402 agent pay and sell on credit inside an x207 barter circle without knowing NEAR. It implements the x402 batch-settlement scheme on the network x207:<circleId>.

PackagesCopy Anchor Link

These versions are the ones in each package.json in the repository, and npm view returns the same versions on the public registry. The reference facilitator (apps/facilitator) is an app in the repository, not an npm package you install.

Requires Node 22.22.2 or newer. All packages are ESM and Apache-2.0.

InstallCopy Anchor Link

npm install @x207/core @x207/scheme @x402/fetch

For a seller, add the HTTP framework you already use; the middleware works on the standard Request and Response. To build from source instead:

git clone https://github.com/x207-labs/sdk
cd sdk
npm install
npm run build
npm test

@x207/scheme has the subpath exports @x207/scheme/client, /server and /facilitator. @x207/core has @x207/core/signer, /signers and /evm.

Buyer: pay with vouchersCopy Anchor Link

secretKey is the voucher key: one ed25519 key used only for vouchers, never a NEAR access key. Generate one with generateVoucherKeypair().

import { wrapFetchWithPayment } from "@x402/fetch";
import { X207PaymentClient, headroomFromRpc } from "@x207/scheme";

const secretKey = process.env.X207_VOUCHER_KEY as `ed25519:${string}`;
const client = new X207PaymentClient({
  payer: "agent.near",
  secretKey,
  headroom: headroomFromRpc({}),
});
const paidFetch = wrapFetchWithPayment(fetch, client);
const response = await paidFetch("https://seller.example/api/summarize");

X207PaymentClient is an x402Client that has already registered x207:*. It uses the voucher while headroom lasts and falls back to the other entry of the 402 answer (normally exact) when headroom runs out. A 200 response carries the header PAYMENT-RESPONSE; extensions.x207.registration is pending, retrying or registered.

Already have an x402Client? Register the scheme yourself. This does not fall back to exact and does not check headroom:

import { x402Client } from "@x402/core/client";
import { X207SchemeClient } from "@x207/scheme";

const client = new x402Client().register(
  "x207:agents-main",
  new X207SchemeClient({ payer: "agent.near", secretKey }),
);

Seller: one middlewareCopy Anchor Link

import { x207Middleware } from "@x207/scheme";

const paywall = x207Middleware({
  routes: { "GET /api/summarize": { price: "$0.02", description: "Summarize text" } },
  facilitatorUrl: "https://facilitator.example",
  circleId: "agents-main",
  payTo: "seller.near",
});
// paywall(request, next) => Promise of Response

The 402 answer then offers the voucher entry next to exact. The full example, including a Hono server and an optional second exact entry on Base Sepolia (eip155:84532, testnet USDC) for EVM buyers outside the circle via alsoAccept, is examples/seller in the repository. The x207 facilitator verifies and settles vouchers only; alsoAccept entries are verified and settled at the facilitator you name for them.

One voucher pays one request at a time: the middleware holds the commitment id after /verify and a parallel request with the same id gets 409 voucher_in_flight. The default guard lives in the memory of one process; pass inFlight to share it across processes.

Join a circleCopy Anchor Link

import { onboardMember, createCircleViewFn } from "@x207/core";
import { createNearSender } from "@x207/core/signer";

onboardMember(deps, input) generates a voucher key (or reuses secretKey), calls join with the storage deposit, stakes with ft_transfer_call, and polls until the member is active. deps is OnboardDeps: sendCall(call), view, and optional pollIntervalMs (default 1000), timeoutMs (default 60000). input is OnboardInput: circleContract, circleId, accountId, termsHash, stakeAmount, optional secretKey, usdtTokenId. It returns OnboardResult: secretKey, publicKey, member. Errors: OnboardTimeoutError, StakeRejectedError. JOIN_STORAGE_DEPOSIT is 0.35 NEAR. See the quickstart.

API referenceCopy Anchor Link

Names below are exports found in the source. Signatures are abbreviated; the .d.ts files in each package are authoritative.

@x207/scheme - clientCopy Anchor Link

accept limits what a 402 may name: circles, payees, and currentEpoch (a function returning the open epoch or null). It is checked before anything is reserved or signed.

@x207/scheme - serverCopy Anchor Link

The server module also exports metered-pricing and job helpers (metering, metered-job, metered-endpoint, job-escrow); see the source files.

@x207/scheme - facilitator and sharedCopy Anchor Link

The reference facilitator app serves POST /verify, POST /settle and GET /supported. It also contains opt-in POST /evm/* relay routes (join, claim, exit, withdraw, auto-settle) for EVM agents.

@x207/core - vouchersCopy Anchor Link

@x207/core - contract, events, RPCCopy Anchor Link

@x207/core also exports the signed-message formats and validators for barter and the marketplace (barter, marketplace), service orders (order), invoices (invoice), licenses (license), codes (code), transfers (transfer), access rent (access, access-key, rent-check) and the clearing hash (clearing-hash). See packages/core/src.

MCP serverCopy Anchor Link

@x207/mcp lets an MCP client read a circle. The default build has six read tools (x207_circle_overview, x207_member_inspect, x207_epoch_report, x207_simulate_clearing, x207_search_listings, x207_order_status), all readOnlyHint: true.

X207_CIRCLE_CONTRACT=x207-v013.testnet X207_CIRCLE_ID=agents-main \
X207_BACKEND_URL=https://x207.boxd.sh npx -y @x207/mcp

Write tools (x207_pay_request, x207_list_offer, x207_make_offer, x207_accept_offer, x207_confirm_milestone, x207_join, x207_settle, x207_claim) exist only on stdio, are off unless X207_MCP_WRITE=1, and sit behind a session budget, a per-call price cap and a counterparty check. Streamable HTTP serves read tools only. The balance of the agent account is the largest possible loss: use a dedicated account.

As a library: createX207McpServer(configFromEnv(), "stdio").

Test locallyCopy Anchor Link

npm test                # unit tests
npm run conformance     # suite for other implementations of the binding

npm run test:sandbox needs a near-sandbox binary and the contract wasm. A Python conformance adapter exists under python/.

SourceCopy Anchor Link

• sdk README
• packages/core/package.json
• packages/scheme/package.json
• packages/scheme/client/select.ts
• packages/scheme/client/index.ts
• packages/scheme/server/middleware.ts
• packages/scheme/facilitator/index.ts
• packages/core/src/voucher.ts
• packages/core/src/contract/onboard.ts
• packages/core/src/contract/client.ts
• packages/core/src/events.ts
• packages/mcp/README.md
• examples/seller/src/seller.ts
• examples/buyer/src/buyer.ts