Agents API

Agents API, yapay zeka ajanı kimliğini düzenler ve yönetir: ajanlara kapsamlanan (operatörlerine değil) did:solidus DID’leri, BBS+ kimlik bilgileri, zincir üstü ERC-8004 pasaportları ve harcama yetkilendirmeleri — bir karşı tarafın Solidus’a geri çağrı yapmadan kontrol edebileceği, kapsamlı, doğrulanabilir bir harcama yetkisi.

Temel URL: https://agents.solidus.network/v1

Bu, @solidus/mcp’nin ve ajan SDK’larının doğrudan kullandığı yüzeydir.

Tam spesifikasyon

Bu sayfadaki her rota, sunucunun istekleri doğrulamak için kullandığı aynı zod şemalarından üretilir — spesifikasyon elle bakımı yapılmadığı için sunucunun gerçekte yaptığından sapamaz. Bu sayfa küratörlüğü yapılmış bir tur niteliğindedir, kapsamlı referans değildir; her rotanın eksiksiz, güncel istek/yanıt biçimi için şunları kullanın:

• Etkileşimli referans: https://agents.solidus.network/documentation
• Ham OpenAPI 3.1 belgesi: https://agents.solidus.network/openapi.json

Kimlik Doğrulama

Operatöre kapalı rotalar, ikisi de Authorization: Bearer <token> olarak gönderilen, birbirinin yerine geçebilen iki kimlik bilgisi biçimiyle tek bir operatorBearer şemasını kabul eder:

• Operatör JWT’si — POST /v1/operators tarafından basılır, sunucunun yapılandırılmış TTL’sine göre sona erer.
• API anahtarı — uzun ömürlü programatik/entegratör kullanımı için POST /v1/api-keys’den alınan, iptal edilebilir bir sk_... anahtarı.

curl https://agents.solidus.network/v1/agents \
  -H "Authorization: Bearer sk_..."

Az sayıda rota tasarım gereği herkese açıktır — kimlik doğrulama gerekmez, çünkü yetkilendirme kanıtı isteğin kendisinde taşınır:

• POST /v1/mandates/check — aşağıdaki yetkilendirme-kontrol akışı
• POST /v1/credentials/verify — canlı kimlik bilgisi doğrulama
• GET /v1/agents/{agentId}/card, GET /v1/credentials/{credentialId}/descriptor, GET /v1/status-lists/{listId} — çözümlenebilir herkese açık belgeler

Ana akış: bir operatör kaydedin, bir ajan oluşturun

# 1. Register an operator — returns a bearer token
curl -X POST https://agents.solidus.network/v1/operators \
  -H "content-type: application/json" \
  -d '{"kyc": {"credentialRef": "urn:solidus:credential:kyc-abc", "assuranceLevel": "substantial"}}'

// Response 201
{
  "operator": { "id": "...", "tenantId": "...", "kycAssuranceLevel": "substantial", "createdAt": "..." },
  "token": "eyJhbGciOiJFZERTQSIs..."
}

# 2. Create an agent under that operator — gets its own did:solidus DID
curl -X POST https://agents.solidus.network/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \
  -H "content-type: application/json" \
  -d '{"custody": "managed"}'

// Response 201
{
  "agent": {
    "id": "...",
    "operatorId": "...",
    "did": "did:solidus:testnet:...",
    "custody": "managed",
    "status": "active",
    "capabilities": [],
    "passport": null,
    "createdAt": "..."
  }
}

Ana akış: yetkilendirme kontrolü — kilit özellik

Bir harcama yetkilendirmesi, bir ajana bir limite kadar, bir para biriminde, bir hat üzerinden, bir son kullanma tarihine kadar harcama yapma yetkisi veren bir BBS+ kimlik bilgisidir — POST /v1/agents/{agentId}/mandates üzerinden bir kez düzenlenir, ardından düzenleyen operatöre hiç geri çağrı yapılmadan herhangi bir karşı taraf tarafından kontrol edilebilir. Kanıt, bir X-Solidus-Mandate zarf başlığı olarak taşınır; kontrol herkese açıktır, kimlik doğrulama gerektirmez ve her adımda hataya kapalıdır (bilinmeyen yetkilendirme, süresi dolmuş, iptal edilmiş, limit aşımı, yanlış para birimi, yanlış hat).

Bu, tam olarak @solidus/mcp’nin check_mandate aracının çağırdığı şeydir:

curl -X POST https://agents.solidus.network/v1/mandates/check \
  -H "content-type: application/json" \
  -d '{
    "envelope": "<the X-Solidus-Mandate header value>",
    "amount": "12.50",
    "currency": "USDC",
    "rail": "x402"
  }'

// Response 200 — authorized
{
  "authorized": true,
  "agentDid": "did:solidus:testnet:...",
  "principalDid": "did:solidus:testnet:...",
  "maxAmount": "50",
  "expiresAt": "2026-08-01T00:00:00.000Z",
  "verifiedAsOf": "2026-07-22T01:00:00.000Z"
}

// Response 200 — denied (any reason: unknown mandate, expired, revoked, over-limit, wrong currency/rail, invalid proof)
{
  "authorized": false,
  "reason": "mandate revoked"
}

authorized/reason, @solidus/mcp tarafından olduğu gibi (verbatim) iletilir — tüm ürünü güvenilir kılan tam olarak bu ret sözleşmesidir ve karşılık gelen bir SDK sürümü olmadan değişmez.

Rota dizini

Her rotanın tam istek gövdesi, yanıt biçimi ve durum kodları için bkz. https://agents.solidus.network/documentation.

Hata biçimi

Hatalar, her rotada aynı biçimde RFC 7807 Problem Details ’ı izler:

{
  "type": "https://solidus.network/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "envelope: Required",
  "instance": "/v1/mandates/check"
}

Üretilen istemcilerin kapsamı

Üretilen bir istemci (Go, Python ve devam etmekte olan diğerleri) yalnızca bu HTTP yüzeyini sarmalar. @solidus/agent-identity’nin BBS+ seçici ifşa, anahtar yönetimi veya kimlik bilgisi paketi yardımcılarının yerini almaz — bunlar kütüphanedir, HTTP sarmalayıcı değildir. Bunun için TypeScript SDK paketlerini kullanın; API’yi başka bir dilden çağırmak için üretilen bir istemciyi (veya doğrudan bu spesifikasyonu) kullanın.