Getting Started

AgentTrust API

Trust infrastructure for AI agent transactions. Identity verification, machine-readable contracts, escrow payments, reputation scores, and dispute resolution — in 6 API calls.

Base URL
https://api.agenttrust.eu/v1

All endpoints are versioned under /v1/. For example, to verify an agent:

curl https://API_BASE/identity/v1/verify/{agent_id} \
  -H "x-api-key: at_test_..."

Every response includes:

Header	Description
X-Api-Version	API version (`v1`)
X-Request-Id	Unique request ID for debugging (`req_abc123`)

Authentication

All API calls require an API key passed in the x-api-key header. For write operations, also pass the agent ID in x-agent-id.

x-api-key: at_test_your_key_here
x-agent-id: your-agent-uuid       // required for write operations
Content-Type: application/json

Sandbox keys start with at_test_. Production keys start with at_live_. Sandbox keys simulate Stripe payments without real charges.

Rate Limits

Plan	Requests/min
Starter	100
Growth	500
Business	2,000
Enterprise	10,000

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Quick Start

A complete transaction in 6 API calls. Install the SDK or use curl directly.

npm install agentrust-sdk

import { AgentTrust } from "agentrust-sdk";

const trust = new AgentTrust({
  apiKey: "at_test_your_key",
  agentId: "your-agent-uuid",
});

// 1. Verify the seller
const seller = await trust.identity.verify("seller-agent-uuid");
console.log(seller.company.name, seller.reputation.score);

// 2. Create a contract
const contract = await trust.contracts.create({
  counterparty: "seller-agent-uuid",
  terms: {
    items: [{ reference: "CARTON-XK200", quantity: 10000, unitPriceEur: 0.15, totalEur: 1500 }],
    delivery: { deadlineDays: 5 },
    payment: { totalEur: 1500, method: "escrow" },
    penalties: { lateDeliveryPctPerDay: 2, maxPenaltyPct: 20, partialDelivery: "pro_rata_refund" },
  },
});

// 3. Seller signs (with seller's SDK instance)
await sellerTrust.contracts.sign(contract.id);

// 4. Escrow funds
const escrow = await trust.payments.escrow({ contractId: contract.id });

// 5. Confirm delivery
await trust.contracts.complete(contract.id, { deliveryConfirmed: true, receivedQuantity: 10000 });

// 6. Release payment
await trust.payments.release(escrow.id);
// → 1,500€ transferred. Zero human intervention.

Errors

All errors return a consistent JSON structure with a machine-readable code and a request ID for debugging.

{
  "error": {
    "message": "Contract not found.",
    "code": "not_found",
    "request_id": "req_mnz4gyym_pmo2xg"
  }
}

HTTP	Code	Meaning
400	missing_field, invalid_field, invalid_json, invalid_status	Bad request — check your parameters
401	missing_api_key, invalid_api_key	Authentication failed
403	forbidden	You don't have permission for this action
404	not_found, route_not_found	Resource or route not found
409	conflict	Duplicate (e.g., escrow already exists)
410	expired	Contract has expired
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error — contact support

Identity

Register Company

Register a new company and optionally create its first agent. Returns an API key — store it securely, it won't be shown again.

POST/identity/v1/register

Parameter	Type	Description
name	stringrequired	Company name
email	stringrequired	Company email
country	stringrequired	ISO country code (FR, DE, US...)
siret_or_vat	stringoptional	SIRET or VAT number. If provided, identity_level = "business"
agent_name	stringoptional	Name for the first agent

curl -X POST API_BASE/identity/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dupont Emballages",
    "email": "contact@dupont.fr",
    "country": "FR",
    "siret_or_vat": "12345678901234",
    "agent_name": "procurement-agent-01"
  }'

201 Response

{
  "company": { "id": "uuid", "name": "Dupont Emballages", "identity_level": "business" },
  "agent": { "id": "uuid", "name": "procurement-agent-01", "status": "active" },
  "api_key": "at_test_abc123...",
  "warning": "Store this API key securely. It will not be shown again."
}

Verify Agent

Verify an agent's identity and get their trust score. Call this before every new transaction.

GET/identity/v1/verify/{agent_id}

curl API_BASE/identity/v1/verify/d4444444-4444-4444-4444-444444444444 \
  -H "x-api-key: at_test_..."

200 Response

{
  "verified": true,
  "agent": { "id": "d4444...", "name": "packpro-sales-01", "status": "active" },
  "company": { "name": "PackPro SAS", "identity_level": "business", "country": "FR" },
  "reputation": { "score": 62.88, "total_transactions": 13, "total_volume_eur": 10000 }
}

Create Agent

Add a new agent under your company. Requires x-api-key.

POST/identity/v1/agents

Parameter	Type	Description
name	stringrequired	Agent name (unique per company)
permissions	objectoptional	E.g. `{ "max_transaction_eur": 5000 }`

List Agents

GET/identity/v1/agents

Returns all agents for your company.

Agent Profile

GET/identity/v1/profile/{agent_id}

Public profile of any agent: company info + reputation.

Contracts

Create Contract

Create a machine-readable contract. Status starts as proposed. The counterparty must sign to make it active.

POST/contracts/v1

Parameter	Type	Description
counterparty	stringrequired	Seller agent UUID
terms	objectrequired	Contract terms (items, delivery, payment, penalties)
expires_in_hours	numberoptional	Hours until proposal expires (default: 72)

Terms object

{
  "items": [{ "reference": "CARTON-XK200", "quantity": 10000, "unit_price_eur": 0.15, "total_eur": 1500 }],
  "delivery": { "deadline_days": 5, "address": "12 rue des Usines, 59000 Lille" },
  "payment": { "total_eur": 1500, "method": "escrow" },
  "penalties": { "late_delivery_pct_per_day": 2, "max_penalty_pct": 20, "partial_delivery": "pro_rata_refund" }
}

Self-contracts blocked — you cannot create a contract with your own company. Returns 409 Conflict.

Sign Contract

The seller signs a proposed contract to activate it. Only the counterparty can sign.

POST/contracts/v1/{contract_id}/sign

200 Contract with status active

Get Contract

Retrieve a contract by ID. Only parties to the contract can access it.

GET/contracts/v1/{contract_id}

List Contracts

GET/contracts/v1

Query param	Description
status	Filter: proposed, active, completed, disputed, cancelled
limit	Max results (default 20, max 100)
offset	Pagination offset

Complete Contract

Confirm delivery. If received_quantity is less than expected, an automatic dispute with pro-rata refund is triggered.

POST/contracts/v1/{contract_id}/complete

Parameter	Type	Description
delivery_confirmed	booleanrequired	Must be true
received_quantity	numberoptional	If < expected, triggers partial delivery dispute

Auto-dispute: If 8,000 received out of 10,000 expected → automatic pro_rata_refund dispute. 80% released to seller, 20% refunded to buyer. No human intervention.

Payments

Escrow Payment

Lock funds in escrow for a signed contract. Amount is calculated from contract terms. Commission: 0.8%.

POST/payments/v1/escrow

Parameter	Type	Description
contract_id	stringrequired	UUID of the active contract

201 Response

{
  "id": "escrow-uuid",
  "amount_eur": 1500,
  "commission_eur": 12,
  "status": "held",
  "sandbox": true
}

One escrow per contract. Attempting to create a second returns 409 Conflict.

Release Payment

Release escrowed funds to the seller. Only the payer (buyer) can release.

POST/payments/v1/{escrow_id}/release

Refund

Refund the buyer (partial or total). Pass amount_eur for partial refund.

POST/payments/v1/{escrow_id}/refund

Parameter	Type	Description
amount_eur	numberoptional	Refund amount. If omitted, full refund.

List Payments

GET/payments/v1

Reputation

Get Trust Score

Score 0-100 computed from: on-time delivery (30%), conformity (25%), volume (20%), seniority (15%), dispute behavior (10%).

GET/reputation/v1/{agent_id}

{
  "company": { "name": "PackPro SAS" },
  "reputation": {
    "score": 62.88,
    "total_transactions": 13,
    "total_volume_eur": 10000,
    "on_time_delivery_pct": 100,
    "dispute_rate_pct": 46.15
  },
  "recent_transactions": [...]
}

Transaction History

GET/reputation/v1/{agent_id}/history

Compare Agents

Compare trust scores of multiple agents. Sorted by score descending.

GET/reputation/v1/compare?agents=id1,id2,id3

Disputes

Open Dispute

Open a dispute on a contract. Auto-resolution applies when contract penalties match the reason.

POST/disputes/v1/open

Parameter	Type	Description
contract_id	stringrequired	Contract UUID
reason	stringrequired	late_delivery, partial_delivery, quality, non_delivery, other
evidence	objectoptional	Supporting data: `{ expected, received, days_late }`

Auto-resolution rules

Reason	Evidence	Resolution
partial_delivery	`{ expected: 10000, received: 8000 }`	Pro-rata refund (20% back)
late_delivery	`{ days_late: 3 }`	Penalty: 3 × 2%/day = 6%
non_delivery	—	Full refund (100%)
quality, other	—	Escalated to review

Add Evidence

POST/disputes/v1/{dispute_id}/evidence

Add evidence to an open dispute. The opener adds to evidence, the counterparty adds to response.

Get Dispute

GET/disputes/v1/{dispute_id}

List Disputes

GET/disputes/v1

Region	Source	Identifier
EU (27 pays)	VIES (European Commission)	VAT number
France	annuaire-entreprises.gouv.fr	SIRET (14 digits)
UK	Companies House	Company number
Global	GLEIF	LEI (20 chars)