Skip to content

feat(x402): add a nano:mainnet offer family verified by block_info #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dhyabi2 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(x402): add a nano:mainnet offer family verified by block_info #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,16 +279,16 @@ See [docs/configuration.md](docs/configuration.md).

## Protocol support

| Protocol | Status | Pinned revision |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
| **HTTP** | Supported | native routes |
| **MCP** | Supported | `2026-07-28` and `2025-11-25`, `@modelcontextprotocol/server@2.3.0` |
| **x402** | Supported | x402 v2 (`@x402/core`, `@x402/evm`, `@x402/svm`, `@x402/near`), scheme `exact`, EVM and Solana; NEAR partial |
| **MPP** | Experimental | `mppx@0.13.1`, `charge` + `evm` + EIP-3009, USDC on Base Sepolia and Base |
| **A2A** | Experimental | A2A v1.0.1, binding `JSONRPC`, method `SendMessage`, x402 extension |
| **ACP** | Experimental | ACP `2026-04-17`, REST checkout + discovery |
| **AP2** | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification |
| UCP | Planned | no implementation |
| Protocol | Status | Pinned revision |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **HTTP** | Supported | native routes |
| **MCP** | Supported | `2026-07-28` and `2025-11-25`, `@modelcontextprotocol/server@2.3.0` |
| **x402** | Supported | x402 v2 (`@x402/core`, `@x402/evm`, `@x402/svm`, `@x402/near`), scheme `exact`, EVM and Solana; NEAR partial; Nano experimental |
| **MPP** | Experimental | `mppx@0.13.1`, `charge` + `evm` + EIP-3009, USDC on Base Sepolia and Base |
| **A2A** | Experimental | A2A v1.0.1, binding `JSONRPC`, method `SendMessage`, x402 extension |
| **ACP** | Experimental | ACP `2026-04-17`, REST checkout + discovery |
| **AP2** | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification |
| UCP | Planned | no implementation |

[AP2](docs/protocols/ap2.md) is an authorization method, not a transport. It verifies a
mandate before a paid resource settles; the gateway does not issue the mandate
Expand Down
35 changes: 35 additions & 0 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,40 @@ payments:
slow backend call is refused at settlement, and the client signs again; use
`upfront` for handlers that can outlast `maxTimeoutSeconds`.

### Nano

Experimental. Nano options settle the native coin, XNO, which has no fees and
no tokens. The buyer publishes a send block to `payTo` first and presents its
hash; the gateway reads that block from a Nano node at `rpcUrl`. It holds no
key, signs nothing and broadcasts nothing, and no facilitator is called, though
the `facilitator` block and the mainnet guardrails still apply to the rail.

```yaml
payments:
x402:
network: nano:mainnet
rpcUrl: ${NANO_RPC_URL} # a node's HTTP RPC
payTo: ${NANO_MERCHANT_ADDRESS} # nano_...; no asset fields: XNO
```

- `payTo` is a `nano_` (or legacy `xrb_`) address with a valid checksum.
`asset` may be omitted or set to `XNO`; `assetDecimals` is 30, so a price of
`0.001` is 10^27 raw.
- The gateway has no XNO exchange rate. A resource with a Nano offer must be
priced in `XNO`, and its offer list may hold only Nano offers; give it its
own [`x402.accepts`](#a-resources-own-offers) to keep USDC offers on the
other resources.
- Verification requires a confirmed (cemented) `state` block of subtype `send`
whose `link_as_account` is `payTo` and whose amount is at least the price.
A block not yet confirmed or not yet seen is refused, and the client can
present it again. A node that does not answer is
`PAYMENT_PROVIDER_UNAVAILABLE`.
- The block hash is the replay key, so one send pays for one request. A send
is public once published: use a `payTo` that receives nothing but payments
for this gateway, since any unclaimed send to it can be presented by whoever
presents it first.
- Health checks that the node answers `version` for the `live` network.

### Several options

Use `options` to offer x402 resources on several networks or in several
Expand Down Expand Up @@ -584,6 +618,7 @@ development address, and either a facilitator credential or
| `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | Solana Devnet | testnet | [remote facilitator only](#solana) |
| `near:mainnet` | NEAR | mainnet | [remote facilitator only](#near) |
| `near:testnet` | NEAR Testnet | testnet | [remote facilitator only](#near) |
| `nano:mainnet` | Nano | mainnet | [experimental; no facilitator](#nano) |

Every built-in EVM network is supported: the signing code is the same on
each, and on 2026-10-10 each network's USDC signing domain matched the chain
Expand Down
15 changes: 13 additions & 2 deletions docs/contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,17 @@ persistence must not fail the commerce flow.
- `createX402PaymentProvider` refuses a `maxTimeoutSeconds` that is not a
positive integer with `CONFIG_INVALID`, as config load already did: the
NEAR facilitator refuses every payment under such a value.
- The x402 provider serves Nano offers (`nano:mainnet`, experimental) without
a facilitator.
- `X402NetworkFamily` gains `nano`. A Nano offer's `asset` is `XNO`, its
`assetDecimals` 30 and its `payTo` a checksummed `nano_` address (`xrb_`
is read as the same account and stored as `nano_`).
- The proof's `payload` is `{ blockHash }`: a send block the buyer already
published. Verify and settle read it from the offer's `rpcUrl`
(`block_info`), the facilitator is never called, and settle sends
nothing. The replay key is derived from the network and block hash.
- The descriptor's `supportedSpec` can name `family=nano`; capabilities gain
`exact-nano-send-block`. A Nano offer must be priced in `XNO`.
- x402 verification and settlement `currency` uses the network's default
token symbol when paying that asset, otherwise the resource's currency.
Settlement preserves a differently labeled price, such as `USD`, in
Expand Down Expand Up @@ -392,13 +403,13 @@ Published as `@devlab.group/agent-commerce/x402`.
export interface X402OfferOptions {
readonly network: string; // CAIP-2, for example 'eip155:84532'
readonly rpcUrl: string;
readonly asset: string; // ERC-20 contract, Solana mint or NEAR token account
readonly asset: string; // ERC-20 contract, Solana mint, NEAR token account or 'XNO'
/** The token's EIP-712 domain; an EIP-3009 offer needs both */
readonly assetName?: string;
readonly assetVersion?: string;
readonly assetDecimals: number;
/** Merchant-controlled settlement destination. */
readonly payTo: string; // on Solana the wallet, on NEAR the account
readonly payTo: string; // on Solana the wallet, on NEAR the account, on Nano a nano_ address
/** EVM only. Default 'eip3009'. A Permit2 buyer approves Permit2 for the token first */
readonly assetTransferMethod?: X402AssetTransferMethod;
}
Expand Down
22 changes: 11 additions & 11 deletions docs/protocols.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ subset. Each protocol's page describes that subset in detail.

## Support matrix

| Protocol | Status | Revision | Implemented subset |
| -------- | ------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **HTTP** | Supported | native | resource routes and rail-specific payment headers |
| **MCP** | Supported | MCP `2026-07-28` and `2025-11-25` through `@modelcontextprotocol/server@2.3.0` | tool discovery, invocation, payment-required and error mapping |
| **x402** | Supported | x402 v2, `@x402/core@2.25.0`, `@x402/evm@2.25.0`, `@x402/svm@2.25.0`, `@x402/near@2.25.0` | `exact` on EVM through EIP-3009 or Permit2, on Solana, and on NEAR (partial): challenge, verification, settlement and replay binding |
| **A2A** | Experimental | v1.0.1; negotiation `1.0`; `JSONRPC` binding | Agent Card, `SendMessage`, paid flow and the x402 extension |
| **ACP** | Experimental | stable snapshot `2026-04-17`; REST binding | discovery and the five checkout operations |
| **AP2** | Experimental | v0.2.0, tag 2026-04-28, commit `b4587ac`; Direct mode | closed Checkout Mandate verification before settlement |
| **MPP** | Experimental | drafts at `tempoxyz/mpp-specs@806fdb8`; `mppx@0.13.1` | `charge`/`evm`/EIP-3009 over HTTP, MCP and A2A |
| UCP | Planned | - | no implementation |
| Protocol | Status | Revision | Implemented subset |
| -------- | ------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTP** | Supported | native | resource routes and rail-specific payment headers |
| **MCP** | Supported | MCP `2026-07-28` and `2025-11-25` through `@modelcontextprotocol/server@2.3.0` | tool discovery, invocation, payment-required and error mapping |
| **x402** | Supported | x402 v2, `@x402/core@2.25.0`, `@x402/evm@2.25.0`, `@x402/svm@2.25.0`, `@x402/near@2.25.0` | `exact` on EVM through EIP-3009 or Permit2, on Solana, and on NEAR (partial): challenge, verification, settlement and replay binding; Nano send blocks (experimental) |
| **A2A** | Experimental | v1.0.1; negotiation `1.0`; `JSONRPC` binding | Agent Card, `SendMessage`, paid flow and the x402 extension |
| **ACP** | Experimental | stable snapshot `2026-04-17`; REST binding | discovery and the five checkout operations |
| **AP2** | Experimental | v0.2.0, tag 2026-04-28, commit `b4587ac`; Direct mode | closed Checkout Mandate verification before settlement |
| **MPP** | Experimental | drafts at `tempoxyz/mpp-specs@806fdb8`; `mppx@0.13.1` | `charge`/`evm`/EIP-3009 over HTTP, MCP and A2A |
| UCP | Planned | - | no implementation |

Experimental components are disabled unless configured and support only the
subsets their pages describe. Planned means there is no adapter or endpoint.
Expand All @@ -40,7 +40,7 @@ lists in `agent-commerce doctor`.
and exclusions
- [ACP](protocols/acp.md): headers, checkout operations, the payment boundary,
idempotency, errors, discovery, and exclusions
- [x402](protocols/x402.md): the `exact` scheme on EVM, Solana and NEAR,
- [x402](protocols/x402.md): the `exact` scheme on EVM, Solana and NEAR, Nano (experimental),
several options, payment flows, and mainnet guardrails
- [MPP](protocols/mpp.md): the pinned drafts, the `charge` profile, payment
flow, problem documents, and exclusions
Expand Down
Loading