Skip to content

Démarrage rapide

Votre agent paie une offre x402 en ligne, et vous confirmez que le paiement a été reconnu. Commencez gratuitement sur Base Sepolia avec de l'USDC de test, puis achetez un bien réel sur mainnet.

Il vous faut un agent qui parle MCP, ou un script qui utilise un client x402 v2 standard. Les deux voies sont décrites ci-dessous.

0. Payer depuis rien, en une commande

Avec Node.js 20 ou plus, et rien d'autre :

npx -y @vauban-pay/mcp try

Elle crée votre propre clé dans ~/.vauban-pay, avec les permissions de fichier 0600, sans l'afficher. Elle obtient 1 USDC de test sur Base Sepolia pour cette clé, puis paie notre offre x402 de démonstration avec elle. Elle affiche les transactions de financement et de paiement, et une ligne pour relire le paiement vous-même. L'USDC de test n'a aucune valeur réelle.

Pour faire la même chose sur Starknet Sepolia, avec du STRK de test au lieu de l'USDC de test :

npx -y @vauban-pay/mcp try --network starknet-sepolia

Elle crée votre propre clé Starknet dans ~/.vauban-pay, obtient du STRK de test pour elle, déploie votre compte, paie notre offre x402 de démonstration sur Starknet Sepolia et affiche les transactions. Le STRK de test n'a aucune valeur réelle.

Les étapes 2 à 6 font la même chose à la main sur Base Sepolia, pour voir chaque partie et la brancher dans votre propre agent ou programme.

Ce qu'il vous faut pour les étapes 2 à 6 : Node.js 20 ou plus, et Foundry pour la commande cast.

0b. Essayer les observations de recherche sur un réseau de test

95 observations de recherche sont servies, à l'appel, sur chacun de trois réseaux de test. Vous payez avec de la monnaie de test, qui n'a aucune valeur réelle. Ceci n'est pas un conseil financier. Aucun rendement n'est promis.

  • Base Sepolia : https://demo.pay.vauban.tech/x402-base-sepolia/v1/observations/<observation>, 0,02 USDC par appel.
  • Starknet Sepolia : https://demo.pay.vauban.tech/starknet/v1/observations/<observation>, 0,01 STRK par appel.
  • Solana devnet : https://demo.pay.vauban.tech/x402-solana-devnet/v1/observations/<observation>, 0,02 USDC par appel.

Pour lire le prix de l'une sans payer, appelez son adresse par un simple GET : elle répond 402, avec le prix dans l'en-tête PAYMENT-REQUIRED.

curl -i https://demo.pay.vauban.tech/x402-base-sepolia/v1/observations/btc-usdc-return-1h-v1

Pour en payer une, utilisez un client x402 v2 standard, comme aux étapes 2 à 6 : le prix et le réseau sont dans le 402. Si un appel répond 503 avec un en-tête Retry-After, cette observation n'est pas en vente à ce moment et rien n'est facturé : rappelez après ce nombre de secondes.

Les 95 observations sont les mêmes sur chaque réseau. Remplacez <observation> ci-dessus par l'un de ces noms :

btc-usdc-bipower-vol-1h-v1
btc-usdc-close-vwap-1h-v1
btc-usdc-downside-vol-1h-v1
btc-usdc-drawdown-1h-v1
btc-usdc-high-low-span-1h-v1
btc-usdc-mean-trade-15m-v1
btc-usdc-path-efficiency-1h-v1
btc-usdc-previous-day-pools-v1
btc-usdc-range-4h-v1
btc-usdc-realized-vol-15m-v1
btc-usdc-realized-vol-1h-v1
btc-usdc-realized-vol-4h-v1
btc-usdc-relative-volume-15m-v1
btc-usdc-return-15m-v1
btc-usdc-return-1h-v1
btc-usdc-return-4h-v1
btc-usdc-taker-flow-15m-v1
btc-usdc-taker-imbalance-1h-v1
btc-usdc-trade-count-15m-v1
eth-usdc-bipower-vol-1h-v1
eth-usdc-close-vwap-1h-v1
eth-usdc-downside-vol-1h-v1
eth-usdc-drawdown-1h-v1
eth-usdc-high-low-span-1h-v1
eth-usdc-mean-trade-15m-v1
eth-usdc-path-efficiency-1h-v1
eth-usdc-previous-day-pools-v1
eth-usdc-range-4h-v1
eth-usdc-realized-vol-15m-v1
eth-usdc-realized-vol-1h-v1
eth-usdc-realized-vol-4h-v1
eth-usdc-relative-volume-15m-v1
eth-usdc-return-15m-v1
eth-usdc-return-1h-v1
eth-usdc-return-4h-v1
eth-usdc-taker-flow-15m-v1
eth-usdc-taker-imbalance-1h-v1
eth-usdc-trade-count-15m-v1
pol-usdc-bipower-vol-1h-v1
pol-usdc-close-vwap-1h-v1
pol-usdc-downside-vol-1h-v1
pol-usdc-drawdown-1h-v1
pol-usdc-high-low-span-1h-v1
pol-usdc-mean-trade-15m-v1
pol-usdc-path-efficiency-1h-v1
pol-usdc-previous-day-pools-v1
pol-usdc-range-4h-v1
pol-usdc-realized-vol-15m-v1
pol-usdc-realized-vol-1h-v1
pol-usdc-realized-vol-4h-v1
pol-usdc-relative-volume-15m-v1
pol-usdc-return-15m-v1
pol-usdc-return-1h-v1
pol-usdc-return-4h-v1
pol-usdc-taker-flow-15m-v1
pol-usdc-taker-imbalance-1h-v1
pol-usdc-trade-count-15m-v1
sol-usdc-bipower-vol-1h-v1
sol-usdc-close-vwap-1h-v1
sol-usdc-downside-vol-1h-v1
sol-usdc-drawdown-1h-v1
sol-usdc-high-low-span-1h-v1
sol-usdc-mean-trade-15m-v1
sol-usdc-path-efficiency-1h-v1
sol-usdc-previous-day-pools-v1
sol-usdc-range-4h-v1
sol-usdc-realized-vol-15m-v1
sol-usdc-realized-vol-1h-v1
sol-usdc-realized-vol-4h-v1
sol-usdc-relative-volume-15m-v1
sol-usdc-return-15m-v1
sol-usdc-return-1h-v1
sol-usdc-return-4h-v1
sol-usdc-taker-flow-15m-v1
sol-usdc-taker-imbalance-1h-v1
sol-usdc-trade-count-15m-v1
strk-usdc-bipower-vol-1h-v1
strk-usdc-close-vwap-1h-v1
strk-usdc-downside-vol-1h-v1
strk-usdc-drawdown-1h-v1
strk-usdc-high-low-span-1h-v1
strk-usdc-mean-trade-15m-v1
strk-usdc-path-efficiency-1h-v1
strk-usdc-previous-day-pools-v1
strk-usdc-range-4h-v1
strk-usdc-realized-vol-15m-v1
strk-usdc-realized-vol-1h-v1
strk-usdc-realized-vol-4h-v1
strk-usdc-relative-volume-15m-v1
strk-usdc-return-15m-v1
strk-usdc-return-1h-v1
strk-usdc-return-4h-v1
strk-usdc-taker-flow-15m-v1
strk-usdc-taker-imbalance-1h-v1
strk-usdc-trade-count-15m-v1

1. Acheter un bien réel

Avec la commande buy

Première fois sur Base : buy key new --network base fait votre clé et affiche l'adresse à alimenter en USDC. Puis buy <url>, puis la même ligne avec --consent.

Faites votre clé. Elle affiche l'adresse à alimenter.

npx -y @vauban-pay/mcp buy key new --network base

Envoyez des USDC sur Base à cette adresse.

Lisez l'offre, ce qui ne paie rien (code de sortie 2), puis payez-la avec le jeton de consentement que la première commande a affiché.

npx -y @vauban-pay/mcp buy https://pay.vauban.tech/x402-base-mainnet/v1/intel
npx -y @vauban-pay/mcp buy https://pay.vauban.tech/x402-base-mainnet/v1/intel --consent <token>

Il vous faut seulement des USDC sur Base (les frais de réseau sont inclus dans le prix) : pas de compte Starknet, pas de nœud.

key new écrit un keystore Web3 v3 et le fichier de son mot de passe aléatoire côte à côte, ~/.vauban-pay/base-mainnet.keystore et base-mainnet.password, lisibles par vous seul (mode 0600). buy les retrouve seul. Le mot de passe est à côté du keystore : cela protège comme un simple fichier de clé de ce mode, et pas plus. buy key address --network base affiche de nouveau l'adresse, jamais la clé.

Sur Starknet, il vous faut un compte Starknet qui détient des STRK et qui est déployé. buy key new fait une clé Starknet, gardée dans ~/.vauban-pay/starknet-mainnet.json (mode 0600, jamais affichée), et affiche l'adresse à alimenter et à déployer. Une fois des STRK reçus, buy key deploy --rpc <url> affiche le plus que coûtera son déploiement et un jeton de consentement, et n'envoie rien. La même ligne avec --consent <jeton> le déploie sous cette borne. buy ne contacte aucun nœud Starknet sauf celui que vous nommez, avec --rpc <url> ou STARKNET_RPC_URL ; il n'y a pas de nœud par défaut.

Codes de sortie : 0 payé, 1 non payé, 2 consentement requis, 3 envoyé mais non confirmé (ne payez pas de nouveau avant d'avoir vérifié), 4 un facilitateur sur votre propre machine a signalé une chaîne simulée : ce n'est pas un paiement.

Avec le serveur MCP ou votre propre client

Les étapes sont les mêmes. Ce qui change :

  • l'URL de l'offre, le réseau, l'actif et le bénéficiaire : lisez-les dans l'offre, comme à l'étape 4 ;
  • votre consentement à dépenser de l'argent réel, réseau par réseau, dans PAY_MCP_EVM_I_ACCEPT_MAINNET_SPEND ;
  • sur Ethereum, le contrat USDC dans PAY_MCP_EVM_ASSETS ;
  • le point d'accès et le contrat de ressource Starknet mainnet, nommés par l'offre.
  • la clé : utilisez un keystore à vous, hors de ~/.vauban-pay. La commande buy du README du paquet refuse le keystore et le fichier de mot de passe que les étapes 0 et 2 y laissent, car ce mot de passe est en clair à côté de la clé.

2. Créer une clé dédiée

Utilisez une clé réservée aux paiements de l'agent, approvisionnée seulement de ce que vous comptez dépenser, jamais la clé d'un portefeuille personnel. Tout outil qui écrit un keystore Web3 Secret Storage v3 convient. Avec Foundry :

mkdir -p ~/.vauban-pay && cd ~/.vauban-pay && umask 077
openssl rand -base64 32 > payer.password
cast wallet new . payer --unsafe-password "$(cat payer.password)"

Le keystore est le fichier payer, son mot de passe est dans payer.password, et la commande affiche l'adresse à approvisionner. Les deux fichiers ne sont lisibles que par vous.

3. Obtenir de l'USDC de test

Demandez à Vauban 1 USDC de test sur Base Sepolia, envoyé à l'adresse de l'étape 2 :

cd ~/.vauban-pay
ADDR=$(cast wallet address --keystore payer --password-file payer.password)
curl -s -X POST https://demo.pay.vauban.tech/sponsor/v1/test-usdc \
  -H 'content-type: application/json' -d "{\"address\":\"$ADDR\"}"

La réponse porte le hash de la transaction. Chaque adresse est approvisionnée une seule fois. L'USDC de test n'a aucune valeur réelle. Il ne vous faut que de l'USDC de test : le paiement est une autorisation EIP-3009 signée, que le facilitateur diffuse en payant le gaz.

Si l'appel est refusé, ouvrez le faucet de Circle, choisissez Base Sepolia et demandez de l'USDC de test pour la même adresse.

4. Lire l'offre

GET https://demo.pay.vauban.tech/x402-base-sepolia/v1/quote

répond 402. L'offre est dans l'en-tête de réponse PAYMENT-REQUIRED, en JSON encodé en base64 :

import base64, json, urllib.request, urllib.error
URL = "https://demo.pay.vauban.tech/x402-base-sepolia/v1/quote"
try:
    urllib.request.urlopen(URL)
except urllib.error.HTTPError as e:            # 402 expected
    h = e.headers["payment-required"]
    offer = json.loads(base64.b64decode(h + "=" * (-len(h) % 4)))
    print(offer["resource"], offer["accepts"])

L'offre porte :

champ contenu
scheme exact, exact-pq
network eip155:84532 (Base Sepolia)
asset 0x036CbD53842c5426634e7929541eC2318f3dCF7e (USDC de test)
amount 1000000 (1 USDC de test)
payTo 0x2311C326dC8654FD75cffC5402fDb06D4095d360

5. Payer

Avec le serveur MCP

Ajoutez @vauban-pay/mcp à votre client MCP (Claude Desktop, Claude Code, tout client MCP), avec les chemins absolus de vos deux fichiers :

{
  "mcpServers": {
    "vauban-pay": {
      "command": "npx",
      "args": ["-y", "@vauban-pay/mcp"],
      "env": {
        "PAY_MCP_EVM_KEYSTORE_PATH": "/home/you/.vauban-pay/payer",
        "PAY_MCP_EVM_PASSWORD_PATH": "/home/you/.vauban-pay/payer.password",
        "PAY_MCP_EVM_NETWORKS": "eip155:84532",
        "PAY_MCP_EVM_PAYEES": "0x2311C326dC8654FD75cffC5402fDb06D4095d360",
        "PAY_MCP_EVM_MAX_PER_PAYMENT": "1000000",
        "PAY_MCP_EVM_MAX_PER_SESSION": "5000000"
      }
    }
  }
}

Cette configuration paie au plus 1 USDC de test par paiement et 5 par session, sur Base Sepolia seulement, à ce seul bénéficiaire. Demandez ensuite à votre agent :

Use pay_for_resource on https://demo.pay.vauban.tech/x402-base-sepolia/v1/quote.

Le résultat est paid, avec la ressource, la transaction et le payeur. S'il est unpayable, son code nomme le réglage à corriger.

Avec n'importe quel client x402 v2

Utilisez le client de la fondation x402, pas les anciens paquets v1 :

npm install @x402/fetch @x402/evm viem
// Pay an x402 v2 URL with the x402 foundation's standard client.
// Usage: EVM_PRIVATE_KEY=0x... node pay.mjs <url>
import { wrapFetchWithPaymentFromConfig, x402HTTPClient, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const url = process.argv[2];
const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
console.log("payer", account.address);

const payFetch = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
});
const res = await payFetch(url, { method: "GET" });
const body = await res.text();
const result = new x402HTTPClient(new x402Client()).parsePaymentResult({
  status: res.status,
  getHeader: (n) => res.headers.get(n),
  body: (() => { try { return JSON.parse(body); } catch { return undefined; } })(),
});
console.log("status", res.status, result.paymentStatus);
console.log("payment header", JSON.stringify(result.header ?? null));

6. Confirmer que vous êtes reconnu

Un paiement réglé rend 200. Un reçu enregistre ensuite, sur Starknet, votre adresse EVM comme ayant payé la ressource. Lisez-le par un appel à votre nœud Starknet Sepolia (JSON-RPC v0.10), au bloc "latest", son URL dans STARKNET_SEPOLIA_RPC_URL. Aucun compte ni aucune clé Starknet ne sont nécessaires.

  • contrat : 0x011e92d42cff92edd738ddc9405b3a53b5cce91371c4c520be20e2717f6ac8fa
  • est_ouverte(payer) : sélecteur 0x03600a7e6d7c7be91e03409ac690f0f4547fdb0f5147af3fcd4cc9ef9bbfbf35, calldata [payer], votre adresse EVM en felt hexadécimal simple
curl -s "$STARKNET_SEPOLIA_RPC_URL" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"starknet_call","params":[{"contract_address":"0x011e92d42cff92edd738ddc9405b3a53b5cce91371c4c520be20e2717f6ac8fa","entry_point_selector":"0x03600a7e6d7c7be91e03409ac690f0f4547fdb0f5147af3fcd4cc9ef9bbfbf35","calldata":["0xYOUR_EVM_ADDRESS"]},"latest"]}'

L'appel rend 0x1 une fois votre paiement reconnu, 0x0 sinon. S'il rend 0x0 juste après le paiement, refaites l'appel un peu plus tard.