Skip to main content

Installation

Published on npm (version 1.2.0). It runs on Node.js 18 or later, Bun, Deno and edge runtimes. Source: xenarch-sdks/js/sdk. The client has five parts:

Create a client

Options

In Node.js you can reuse the CLI’s session and local wallet from ~/.xenarch/config.json:
fromConfig throws SessionExpiredError when no session is stored. Run npx xenarch agent login first.

Pay: sdk.x402

pay(url) signs an EIP-3009 USDC authorization from your wallet to the seller’s wallet, posts it to the facilitators the gate lists until one settles it on Base (the facilitator pays the gas), then fetches the URL again with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash and returns that response. Things to know:
  • pay works on URLs gated by Xenarch, whose 402 body carries a gate_id. For any other URL it throws NotGatedError.
  • pay does not apply spend caps or a price limit. Check gate.accepts[0].maxAmountRequired (USDC base units, 6 decimals) before you call it.
Other methods:

Get paid: sdk.merchant

Every field is a tagged value. to, amount, currency, network and kind are required and must be "lit" at creation. Read the full field list with sdk.merchant.links.schema().
create validates first and throws PayLinkValidationError (with .missing and .errors) when a field is missing or invalid. It signs the terms with privateKey, which must belong to the session’s wallet. Revoke a link with sdk.merchant.links.revoke(linkId, { confirm: true }). See Pay links for the link kinds and the hosted checkout.

Report metered usage

For a metered subscription link, report usage increments with the link’s webhook secret:
units is an increment, not a running total. A repeated idempotencyKey is ignored. See Subscriptions.

Agent control plane: sdk.agent

setCaps and setScope replace the whole state. Pass null for a cap to remove it. Other methods: profile(), summary(period), getCaps(), resetDayCap(), getScope(), receipts(query), keys.list(), keys.rotate(id), keys.revoke(id).

Public reads: sdk.info

Verify webhooks: sdk.webhooks

The header has the form t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with the webhook secret. verify rejects timestamps more than 300 seconds from now. Change that with { toleranceSeconds: 600 }, or pass { throwOnFailure: true } to get a WebhookVerificationError instead of false. See Webhooks.

Errors

Asset constants

There is no Xenarch contract on the payment path. The only on-chain address involved is native USDC on Base mainnet (chain id 8453):