référence

référence de l'api rest

Les mêmes capacités que les outils MCP, en HTTPS et JSON classiques. Les agents utilisent /v1/agent/*, les admins /api/*, sur une seule URL de base.

principes

élément	valeur
URL de base	`https://mcp.nostro.ag`
authentification	`Authorization: Bearer nst_…` sur `/v1/agent/`, `Bearer nsa_…` sur `/api/`
format	JSON en entrée et en sortie. Envoyez `content-type: application/json` sur les POST.
montants	Nombres en euros dans les requêtes ; objets `{value, currency}` à valeurs texte pour les soldes.
CORS	Ouvert (`*`). Les clés sont des secrets bearer : appelez depuis un serveur, pas un navigateur.
santé	`GET /health` → `{"ok":true,"bankMode":"…"}`

exemple

curl -s -X POST https://mcp.nostro.ag/v1/agent/pay \
  -H "Authorization: Bearer $NOSTRO_AGENT_KEY" \
  -H "content-type: application/json" \
  -d '{"amount":49,"merchant":"Vercel","mcc":"5734","description":"Pro plan"}'

POSThttps://mcp.nostro.ag/api/sandbox/signup

Public, sans authentification. Crée un espace sandbox doté de 10 000 EUR fictifs, une clé admin et la clé d'un demo-agent (500 par paiement, 2 000 par jour, approbation au-delà de 250). Les clés ne sont renvoyées qu'une fois.

nom	type		description
`email`	`string`	requis	Adresse pour vous joindre au sujet de la préversion.
`company`	`string`	optionnel	Nom de l'entreprise, utilisé pour l'espace.
`lang`	`string`	optionnel	« en » (défaut) ou « fr » : langue du demo-agent et des messages de limite.

corps

{
  "email": "you@company.com",
  "company": "Acme",
  "lang": "en"
}

201 Created

{
  "workspace_id": "ws_7c1e9a42b0d3",
  "admin_key": "nsa_9Hc2••••••••••••••••••••••••",
  "agent": {
    "id": "agt_3f2b8d10",
    "name": "demo-agent",
    "key": "nst_k3Jd••••••••••••••••••••••••",
    "policy": {
      "currency": "EUR",
      "perTxMax": 500,
      "dailyMax": 2000,
      "monthlyMax": 5000,
      "approvalAbove": 250,
      "allowedMccs": [],
      "blockedMerchants": [],
      "transfersEnabled": false,
      "transferApprovalAbove": 0
    }
  },
  "mcp_url": "https://mcp.nostro.ag/mcp",
  "balance": {
    "amount": 10000,
    "currency": "EUR",
    "fake": true
  },
  "sandbox": true
}

limite	valeur	en cas de dépassement
espaces sandbox par e-mail	3	`429`
inscriptions par IP	10 par heure	`429`
inscriptions au total	500 par heure	`429`
e-mail invalide		`400`

Depuis un navigateur, cet endpoint n'est appelable que depuis nostro.ag et docs.nostro.ag (CORS). Les appels serveur et terminal ne sont pas concernés.

GET /api/sandbox/stats

GEThttps://mcp.nostro.ag/api/sandbox/stats

Public, sans authentification, cache de 30 s. Compteurs agrégés de la sandbox publique (domaines de test exclus).

200 OK

{
  "workspaces": 128,
  "agents": 241,
  "payments": 1873,
  "volume_eur": 96412.5
}

endpoints agent

Clé : nst_…. Chaque appel est limité à l'agent qui possède la clé.

GET /v1/agent/wallet

GEThttps://mcp.nostro.ag/v1/agent/wallet

Budget restant (jour, mois), plafonds, statut de la carte et solde disponible du compte de l'entreprise. Les agents sont invités à l'appeler avant toute dépense. Identique à l'outil MCP get_wallet.

200 OK

{
  "agent": {
    "id": "agt_3f2b8d10",
    "name": "demo-agent",
    "status": "active"
  },
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "maskedNumber": "4970 •••• •••• 3182",
    "status": "Enabled"
  },
  "accountAvailable": {
    "value": "10000.00",
    "currency": "EUR"
  },
  "budget": {
    "currency": "EUR",
    "perTxMax": 500,
    "approvalAbove": 250,
    "dailyRemaining": 2000,
    "monthlyRemaining": 5000
  },
  "transfersEnabled": false
}

POST /v1/agent/pay

POSThttps://mcp.nostro.ag/v1/agent/pay

Paie un marchand avec la carte virtuelle de l'agent. Évalué d'abord contre le mandat : exécuté, bloqué ou mis en attente d'approbation humaine. Identique à l'outil MCP pay.

nom	type		description
`amount`	`number`	requis	Montant en euros, > 0. Arrondi à 2 décimales, ex. 19.99.
`merchant`	`string`	requis	Nom du marchand. Comparé à blockedMerchants.
`mcc`	`string`	optionnel	Code catégorie marchand, exactement 4 chiffres, ex. 5734. Obligatoire si le mandat a des allowedMccs.
`description`	`string`	optionnel	Objet de la dépense. Enregistré dans le journal d'audit.

corps

{
  "amount": 49,
  "merchant": "Vercel",
  "mcc": "5734",
  "description": "Pro plan, November"
}

200 OK

{
  "status": "paid",
  "transactionId": "vtx_883b5610e2a1",
  "amount": 49,
  "merchant": "Vercel"
}

POST /v1/agent/transfer

POSThttps://mcp.nostro.ag/v1/agent/transfer

Envoie un virement SEPA depuis le compte de l'entreprise, uniquement si le mandat autorise les virements. Le plus souvent soumis à approbation humaine. Identique à l'outil MCP send_transfer.

nom	type		description
`amount`	`number`	requis	Montant en euros, > 0.
`iban`	`string`	requis	IBAN du bénéficiaire. Espaces retirés ; doit respecter ^[A-Z]{2}\d{2}[A-Z0-9]{10,30}$.
`beneficiaryName`	`string`	requis	Nom du bénéficiaire.
`label`	`string`	optionnel	Libellé, 140 caractères max. Par défaut « Nostro <nom de l'agent> ».

corps

{
  "amount": 1200,
  "iban": "FR7630006000011234567890189",
  "beneficiaryName": "Acme SAS",
  "label": "Invoice 2026-114"
}

200 OK

{
  "status": "pending_approval",
  "requestId": "req_51c0aa9e",
  "reason": "Virement soumis à approbation humaine",
  "message": "Demande transmise à un humain de l'entreprise. Vérifie son statut avec get_request_status."
}

GET /v1/agent/requests/:id

GEThttps://mcp.nostro.ag/v1/agent/requests/:id

Statut d'une dépense en attente d'approbation humaine. Un agent ne lit que ses propres demandes. Identique à l'outil MCP get_request_status.

200 OK

{
  "id": "req_ef5c846c",
  "kind": "card_payment",
  "amount": 320,
  "status": "executed",
  "reason": "Au-dessus du seuil d'approbation (250 €)",
  "result": {
    "amount": 320,
    "status": "paid",
    "merchant": "AWS",
    "transactionId": "vtx_acf5376d09be"
  },
  "createdAt": "2026-11-05T09:19:33.478Z",
  "decidedAt": "2026-11-05T09:20:41.561Z"
}

GET /v1/agent/activity

GEThttps://mcp.nostro.ag/v1/agent/activity

Les 50 derniers événements de l'agent, du plus récent au plus ancien. Identique à l'outil MCP list_my_activity.

200 OK

[
  {
    "id": 7,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 320,
    "counterparty": "AWS",
    "decision": "executed",
    "reason": null,
    "bank_ref": "vtx_acf5376d09be",
    "created_at": "2026-11-05T09:20:41.560Z",
    "agent_name": "demo-agent"
  },
  {
    "id": 5,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 900,
    "counterparty": "Apple",
    "decision": "denied",
    "reason": "Dépasse le plafond par transaction (500 €)",
    "bank_ref": null,
    "created_at": "2026-11-05T09:18:02.491Z",
    "agent_name": "demo-agent"
  }
]

endpoints admin

Clé : nsa_…. Limité à l'espace de la clé admin.

méthode	chemin	description	MCP
GET	`/api/overview`	Compte, solde, nombre d'agents actifs, approbations en attente et dépenses du mois.	`overview`
GET	`/api/agents`	Tous les agents non révoqués avec carte, mandat et dépenses en cours.	`list_agents`
POST	`/api/agents`	Crée un agent avec sa carte virtuelle au nom de l'entreprise, son mandat et sa clé API. La clé n'est renvoyée qu'une seule fois.	`create_agent`
GET	`/api/agents/:id`	Un agent (carte, mandat, dépenses).	·
POST	`/api/agents/:id/refresh`	Relit le statut de la carte chez l'émetteur.	·
POST	`/api/swan/bootstrap`	Réservé à l'opérateur (espace owner). Renvoie 403 avec une clé sandbox.	·
POST	`/api/agents/:id/policy`	Modifie le mandat d'un agent. Seuls les champs envoyés changent, le reste est conservé. Modifier monthlyMax met aussi à jour le plafond de la carte.	`update_agent_policy`
POST	`/api/agents/:id/freeze`	Coupe-circuit : bloque immédiatement toute dépense de l'agent. Réversible.	`freeze_agent`
POST	`/api/agents/:id/unfreeze`	Réactive un agent gelé.	`unfreeze_agent`
POST	`/api/agents/:id/revoke`	Révoque la clé de l'agent et annule sa carte. Irréversible.	`revoke_agent`
GET	`/api/requests?status=`	Demandes par statut : `pending` (défaut), `executed`, `failed`, `rejected` ou `all`. 100 max.	`list_pending_approvals`
POST	`/api/requests/:id/approve`	Approuve une demande en attente et l'exécute immédiatement. Une seule décision par demande, même en cas de clics simultanés.	`approve_request`
POST	`/api/requests/:id/reject`	Refuse une demande en attente. Rien n'est débité.	`reject_request`
POST	`/api/fund`	Sandbox uniquement : crédite le registre virtuel de l'espace (virement SEPA entrant simulé, euros fictifs). `{"amount":5000}`	`fund_account`
GET	`/api/events?agentId=&limit=`	Toutes les décisions et opérations de l'espace, des plus récentes aux plus anciennes, éventuellement pour un seul agent. Limite 100 par défaut, 500 max.	`audit_log`

Corps et réponses sont identiques aux outils MCP, à une différence près : POST /api/agents imbrique le mandat sous policy, alors que l'outil MCP prend les champs à plat.

POST /api/agents · body

{
  "name": "procurement-bot",
  "purpose": "Buys SaaS seats",
  "policy": {
    "perTxMax": 200,
    "dailyMax": 600,
    "monthlyMax": 3000,
    "approvalAbove": 100,
    "allowedMccs": [
      "5734",
      "7372"
    ]
  }
}

201 Created

{
  "agent": {
    "id": "agt_91ad04c2",
    "name": "procurement-bot",
    "purpose": "Buys SaaS seats",
    "status": "active",
    "keyPrefix": "nst_Qm7v",
    "card": {
      "id": "vcard_0c44e1b9a7d0",
      "status": "Enabled",
      "maskedNumber": "4970 •••• •••• 7745",
      "consentUrl": null
    },
    "policy": {
      "currency": "EUR",
      "perTxMax": 200,
      "dailyMax": 600,
      "monthlyMax": 3000,
      "approvalAbove": 100,
      "allowedMccs": [
        "5734",
        "7372"
      ],
      "blockedMerchants": [],
      "transfersEnabled": false,
      "transferApprovalAbove": 0
    },
    "spend": {
      "today": 0,
      "month": 0
    },
    "createdAt": "2026-11-05T09:12:04.118Z"
  },
  "apiKey": "nst_Qm7v••••••••••••••••••••••••"
}

POST /api/agents/:id/policy · body

{
  "approvalAbove": 100,
  "blockedMerchants": [
    "casino"
  ]
}

référence de l'api rest

principes#

inscription sandbox#

POST /api/sandbox/signup#

GET /api/sandbox/stats#

endpoints agent#

GET /v1/agent/wallet#

POST /v1/agent/pay#

POST /v1/agent/transfer#

GET /v1/agent/requests/:id#

GET /v1/agent/activity#

endpoints admin#

principes

inscription sandbox

POST /api/sandbox/signup

GET /api/sandbox/stats

endpoints agent

GET /v1/agent/wallet

POST /v1/agent/pay

POST /v1/agent/transfer

GET /v1/agent/requests/:id

GET /v1/agent/activity

endpoints admin