Signed receipts for your API exchanges.
# À quoi sert Datoka API ?
Datoka API délivre un reçu signé associé aux empreintes d'un échange HTTP
déclaré par votre application. Prix : 0,002 USDC sur Base par reçu ; préparer
les empreintes et vérifier les reçus est gratuit.
## 1. Conserver la trace d'une réponse utilisée
Votre application utilise une réponse API pour prendre une décision : résultat
d'un calcul, devis ou état d'une ressource. Elle conserve les octets originaux
chez elle, calcule leurs empreintes localement et obtient un reçu Datoka.
Plus tard, elle vérifie que le fichier présenté correspond bien à l'engagement
signé. Elle peut communiquer le reçu et le contenu au destinataire de son choix.
Le reçu ne démontre pas que le fournisseur a réellement envoyé cette réponse,
ni qu'il en approuve le contenu. Il porte sur la déclaration de l'application.
## 2. Détecter une modification d'archive
Vous archivez des réponses JSON pour un contrôle ultérieur. À la relecture,
vous vérifiez la signature du reçu avec une clé publique de confiance, puis
comparez les empreintes aux fichiers conservés. Une modification du contenu,
même un espace ajouté au JSON, fait échouer cette seconde comparaison.
Datoka ne stocke pas vos fichiers et ne permet pas de les récupérer. Conservez
ensemble le reçu, les octets originaux et les clés publiques de confiance.
Une réponse différente peut être une nouvelle version légitime : un écart
d'empreinte ne suffit pas à conclure à une fraude.
## 3. Documenter l'appel API d'un agent
Votre agent enregistre l'événement correspondant à un appel d'outil HTTP :
identifiants techniques non personnels, méthode, statut et empreintes. Le reçu
permet ensuite de vérifier la déclaration conservée dans le journal de l'agent.
L'intégration peut utiliser HTTP ou MCP ; un client MCP ordinaire peut préparer
et vérifier gratuitement. Payer exige un portefeuille et la prise en charge x402.
Le reçu n'atteste pas le raisonnement de l'agent, l'identité du fournisseur ou
la véracité de la donnée. Il ne garantit pas non plus les dates déclarées par
le client. L'heure d'émission est celle du service, sans horodatage qualifié.
## Quand l'achat apporte une valeur concrète
| Situation de l'agent | Livrable utile | Critère pour acheter |
|---|---|---|
| Transmettre une réponse à un autre agent ou à son client | Reçu signé et, au choix, copie des octets dans un fichier vérifiable hors ligne | Le destinataire accepte Datoka comme émetteur et demande un engagement vérifiable sur la déclaration |
| Conserver les données utilisées pour choisir un devis ou une offre | Version exacte de la réponse et reçu, gardés localement | Une vérification ultérieure de cette déclaration a de la valeur ; le reçu ne garantit ni prix actuel ni acceptation du fournisseur |
| Documenter un changement entre deux réponses d'API | Deux déclarations et leurs reçus, avec les réponses originales | On veut vérifier ce qui a été engagé pour chaque version ; le service ne détermine pas la cause du changement |
| Archiver une réponse obtenue à coût élevé | Reçu et réponse conservée chez le client | Le client veut vérifier l'intégrité de son archive plus tard ; Datoka ne fournit pas de stockage ni de droit de redistribution |
Acheter seulement si la mission de l'agent et le budget autorisé le justifient.
Un reçu coûte 0,002 USDC ; dix reçus distincts coûtent 0,02 USDC au tarif actuel.
Le destinataire ne paie pas pour vérifier. La signature ajoute l'engagement d'un
émetteur tiers sur une déclaration : elle ne transforme pas celle-ci en donnée
indépendamment observée. Si personne n'a besoin de cet engagement, un hachage
local et un journal peuvent suffire. Ne pas acheter systématiquement pour un
appel de santé, une donnée jetable ou une tâche exigeant une preuve d'origine
du fournisseur, que ce produit ne fournit pas.
## Transmettre un dossier vérifiable
Le SDK propose createEvidenceBundle et verifyEvidenceBundle. Le fichier
datoka.api.evidence.v1 conserve la déclaration et le reçu signé ; la réponse
originale peut être incluse volontairement (1 Mio maximum). Aucune clé de
confiance ni autorisation de paiement n'est copiée depuis le résultat payé.
La création et la vérification se font localement, sans appel à Datoka.
Le destinataire fournit ses propres clés publiques de confiance. Un fichier
ne peut pas se déclarer fiable en y ajoutant lui-même une clé. Le rapport
distingue signature valide, réponse conforme, réponse modifiée et réponse absente.
Les autres contenus de l'échange (URL, requête et en-têtes) restent à comparer
séparément avec verifyExchangePayloads. Le format du reçu signé reste inchangé.
```sh
curl --fail https://datoka-api.bhazarstudio.workers.dev/sdk/0.3.8/datoka-api.js -o datoka-api.mjs
curl --fail https://datoka-api.bhazarstudio.workers.dev/sdk/0.3.8/evidence.mjs -o evidence.mjs
curl --fail https://datoka-api.bhazarstudio.workers.dev/sdk/0.3.8/manifest.json -o manifest.json
```
Sous PowerShell, utiliser curl.exe. Avant d'exécuter les scripts téléchargés,
enregistrer ce contrôle dans check-files.mjs puis lancer node check-files.mjs :
```js
import { readFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
const manifest = JSON.parse(readFileSync('manifest.json', 'utf8'));
for (const [remote, local] of [['datoka-api.js', 'datoka-api.mjs'], ['evidence.mjs', 'evidence.mjs']]) {
const expected = manifest.files.find(file => file.path === '/sdk/0.3.8/' + remote)?.sha256;
const actual = createHash('sha256').update(readFileSync(local)).digest('hex');
if (!expected || actual !== expected) throw new Error('Checksum mismatch: ' + local);
}
console.log('Both checksums match the downloaded manifest.');
```
Le manifeste est obtenu sur la même origine HTTPS : ce contrôle détecte une
copie incomplète ou des fichiers mélangés, sans constituer une signature indépendante.
```sh
# Expéditeur : le reçu et la réponse sont déjà conservés localement.
node evidence.mjs pack receipt.json trusted-keys.json evidence.json response.bin
# Destinataire : ses clés de confiance sont obtenues et conservées séparément.
node evidence.mjs verify evidence.json trusted-keys.json
```
Le paramètre response.bin est optionnel. Si présent, son contenu est inclus en
base64 dans le fichier remis : partagez-le uniquement avec un destinataire
autorisé. Le rapport indique responseBodyStatus: matches, differs ou not_included.
Une réponse différente donne valid: false et un code de sortie non nul, même
si la signature du reçu reste valide. Sans réponse, seule la déclaration signée
est vérifiée. Pour imposer un portefeuille attendu, ajouter son scope
wallet:0x… en troisième argument de verify. Aucun paiement n'est déclenché.
## Démarrer
- Test gratuit sans portefeuille : /quickstart.
- Parcours complet avec un reçu payé : /first-receipt.
- Vérification locale dans le navigateur : /verify/.
- Contrats pour les agents : /openapi.json et /mcp.
La capture envoie votre requête au fournisseur une seule fois. Elle transmet
à Datoka uniquement la déclaration avec les empreintes, jamais les corps bruts,
URLs ou en-têtes secrets. Une empreinte n'est pas un chiffrement : évitez de
traiter des valeurs prévisibles comme confidentielles du seul fait du hachage.
## English summary for integrations
Use Datoka API to retain a signed commitment to a declared API exchange, detect
changes to archived response bytes, or document an agent's HTTP tool call.
Keep originals locally. Verify both the receipt signature with trusted issuer
keys and the exact original bytes. The receipt does not prove provider origin,
independent observation, content truth, or accurate client timestamps.
Free preparation and verification; paid issuance costs 0.002 USDC on Base.
Start at /quickstart, then follow /first-receipt for a recoverable purchase.