Concepts

concepts

Six objets expliquent tout Nostro : l'espace, ses agents, leurs clés, leurs mandats, les demandes d'approbation et le journal d'audit. En sandbox, l'argent vit sur un registre virtuel.

espace

Un espace correspond à une entreprise. Il possède un compte en euros (son solde est celui que renvoient overview et get_wallet), une clé admin et tous les agents qui y sont créés. Les identifiants ressemblent à ws_7c1e9a42b0d3. Une inscription sandbox crée un nouvel espace isolé avec 10 000 EUR fictifs et jusqu'à 25 agents.

agents

L'agent est l'unité de contrôle : un agent = une carte virtuelle + une clé API + un mandat. Les agents dépensent sur le compte de l'entreprise via leur carte ; ils ne voient jamais le numéro de carte (masqué) et ne peuvent pas toucher aux autres agents.

status	signification
`active`	Peut dépenser dans les limites de son mandat.
`frozen`	Toute dépense échoue en 403 jusqu'au dégel par un admin. Les approbations en attente ne peuvent pas non plus s'exécuter.
`revoked`	Clé désactivée, carte annulée. Irréversible ; l'agent disparaît de `list_agents`.

L'objet agent, tel que renvoyé par les outils admin :

agent

{
  "id": "agt_3f2b8d10",
  "name": "demo-agent",
  "purpose": "Demo agent (sandbox, fake euros)",
  "status": "active",
  "keyPrefix": "nst_k3Jd",
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "status": "Enabled",
    "maskedNumber": "4970 •••• •••• 3182",
    "consentUrl": null
  },
  "policy": {
    "currency": "EUR",
    "perTxMax": 500,
    "dailyMax": 2000,
    "monthlyMax": 5000,
    "approvalAbove": 250,
    "allowedMccs": [],
    "blockedMerchants": [],
    "transfersEnabled": false,
    "transferApprovalAbove": 0
  },
  "spend": {
    "today": 49,
    "month": 49
  },
  "createdAt": "2026-11-05T09:12:04.118Z"
}

clés

préfixe	portée	où elle vit
`nst_`	Un agent : son portefeuille, ses paiements, son activité, ses demandes.	Dans la config MCP ou l'environnement de l'agent.
`nsa_`	Tout l'espace : agents, mandats, approbations, alimentation, audit.	Uniquement chez des humains : un gestionnaire de secrets, votre terminal.

Les clés sont aléatoires, affichées une seule fois et stockées uniquement sous forme d'empreinte SHA-256. Les 8 premiers caractères (keyPrefix, ex. nst_k3Jd) sont conservés pour distinguer les clés. Voir sécurité.

mandats

Un mandat (le champ policy) est l'ensemble des règles évaluées avant tout mouvement d'argent :

champ	type	défaut	description
`perTxMax`	`number`	`100`	Montant maximum d'un paiement carte, en euros. Au-delà, le paiement est bloqué.
`dailyMax`	`number`	`300`	Dépense exécutée maximum par jour calendaire (UTC), paiements carte et virements cumulés.
`monthlyMax`	`number`	`1000`	Budget mensuel. Également posé comme plafond de dépense sur la carte elle-même (défense en profondeur).
`approvalAbove`	`number`	`50`	Les paiements carte strictement au-dessus de ce montant attendent une approbation humaine au lieu d'être exécutés.
`allowedMccs`	`string[]`	`[]`	Codes catégorie marchand (MCC, 4 chiffres) autorisés. Vide signifie toutes les catégories.
`blockedMerchants`	`string[]`	`[]`	Marchands à bloquer. Correspondance partielle, insensible à la casse, sur le nom du marchand.
`transfersEnabled`	`boolean`	`false`	Autorise ou non l'agent à envoyer des virements SEPA.
`transferApprovalAbove`	`number`	`0`	Les virements strictement au-dessus de ce montant demandent une approbation humaine. 0 signifie que tout virement est revu.

Chaque paiement reçoit l'une de trois issues : autorisé, revu (approbation humaine) ou bloqué. Règles complètes et exemples dans mandats et moteur de règles.

demandes d'approbation

Quand le mandat dit « revoir », Nostro crée une demande (req_…) au lieu de débiter la carte, et renvoie pending_approval à l'agent. Un humain muni de la clé admin l'approuve ou la refuse. L'approbation exécute le paiement immédiatement avec les paramètres d'origine.

status	signification
`pending`	En attente d'un humain.
`executed`	Approuvée et payée (ou virement initié). `result` contient le paiement.
`failed`	Approuvée mais non exécutée (agent gelé, refus banque). `result.reason` précise pourquoi.
`rejected`	Refusée par un humain. Rien n'est débité.

Une seule décision est appliquée par demande, même si deux admins cliquent en même temps ; le second reçoit 400. Les montants en attente ne comptent dans les dépenses du jour ou du mois qu'une fois exécutés.

journal d'audit

Chaque action écrit un événement : qui (agent), quoi (type), combien, avec qui (contrepartie), la décision et sa raison, et une référence (transaction, carte ou demande). Les agents lisent leurs événements avec list_my_activity ; les admins lisent tout avec audit_log.

type	écrit quand
`card_payment`	Un agent tente de payer (quelle que soit l'issue).
`transfer`	Un agent tente un virement SEPA.
`funding`	Le compte sandbox est alimenté.
`agent_created`, `policy_updated`	Un admin crée un agent ou modifie un mandat (le correctif est dans `reason`).
`agent_frozen`, `agent_unfrozen`, `agent_revoked`	Changements de statut.

decision	signification
`executed`	L'argent a bougé (ou l'action admin est appliquée).
`denied`	Bloqué par le mandat.
`pending_approval`	Mis en attente d'un humain ; `bank_ref` est l'id de la demande.
`rejected_by_human`	Un humain a refusé la demande.
`declined_by_bank`	Autorisé par le mandat mais refusé par l'émetteur de la carte (ex. plafond carte).

registre virtuel (sandbox)

En sandbox, il n'y a ni argent réel ni réseau carte réel :

Soldes, cartes et transactions vivent sur un registre virtuel. Les montants sont en euros à 2 décimales, renvoyés en chaînes dans les objets monétaires : {"value":"10000.00","currency":"EUR"}.
pay simule une autorisation et un débit carte. Les débits sont atomiques : des paiements simultanés ne peuvent jamais mettre le solde à découvert (InsufficientFunds). Le plafond mensuel de la carte vaut monthlyMax ; au-delà, l'émetteur refuse avec CardSpendingLimitExceeded.
fund_account crédite des euros fictifs (jusqu'à 100 000 EUR par appel, solde plafonné à 1 000 000 EUR). Les IBAN utilisent le code banque fictif 99999 et ne sont jamais routables ; les numéros de carte commencent par 4970 et sont masqués.
Les marchands sont le nom que vous passez ; aucun argent ne leur parvient. Utilisez n'importe quel MCC à 4 chiffres pour tester les règles de catégorie.
overview renvoie bankMode: "ledger" et workspace.kind: "sandbox", pour que vous sachiez toujours que vous êtes sur le registre simulé. Chaque espace sandbox est isolé : une clé admin ne voit jamais les agents ou demandes d'un autre espace (elle reçoit 404).

espace#

agents#

clés#

mandats#

demandes d'approbation#

journal d'audit#

registre virtuel (sandbox)#