Integration Guide

This guide walks platform operators through a complete Signet integration. By the end, your platform will be able to register agents, report transactions, query trust scores before interactions, and track configuration changes.

How platforms integrate Signet

A typical integration follows four phases: operator onboarding, agent registration, transaction reporting, and pre-transaction score queries.

  1. You apply for an operator account and receive API credentials.
  2. You register each agent on your platform with the Signet API.
  3. After each agent transaction, you report the outcome to Signet.
  4. Before allowing a new transaction, you query the agent's score and act on the recommendation.

Step 1: Apply for an operator account

An operator is the human or organization that controls one or more agents. Apply at agentsignet.com/apply or via the API:

curl -X POST https://api.agentsignet.com/apply \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Smith",
    "email": "alice@example.com",
    "company": "Acme AI Platform",
    "reason": "Integrating trust scoring for third-party agents"
  }'

Once approved, you receive an email containing:

  • Your API key in the format sk_signet_ + 64 hex characters
  • Links to this documentation

Your operator account is the root of your trust hierarchy. All agents you register will be associated with your operator profile, and your Operator Score will reflect the aggregate behavior of your agent fleet.

Step 2: Register agents via API

Register each agent when it first appears on your platform. This creates a Signet ID (SID) that you store alongside your internal agent records.

curl -X POST https://api.agentsignet.com/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-triage-agent",
    "description": "Customer support triage agent",
    "modelProvider": "anthropic",
    "modelName": "claude-sonnet-4-5",
    "tools": ["text-generation", "classification"]
  }'

Response:

{
  "sid": "SID-0x3c9e1a7f5b2d8e04",
  "name": "support-triage-agent",
  "composite_score": 500,
  "confidence": "low",
  "fingerprint": "d4c3b2a1e5f6...",
  "message": "Agent registered successfully"
}

Store the returned sid in your database. You will use it for all subsequent score queries and transaction reports.

Step 3: Report transactions

Signet relies on integrated platforms to report transaction outcomes. Each report contributes to the agent's dimension scores via the EMA update mechanism.

After an agent completes a task on your platform, send a transaction report with the outcome and any relevant dimension signals (0 to 1000):

curl -X POST https://api.agentsignet.com/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": "SID-0x3c9e1a7f5b2d8e04",
    "transactionType": "task_completion",
    "outcome": "success",
    "reliabilitySignal": 900,
    "qualitySignal": 850
  }'

Transaction fields

| Field | Type | Required | Description | |---------------------|--------|----------|----------------------------------------------------------------| | sid | string | Yes | The agent's Signet ID | | transactionType | string | Yes | Transaction type (e.g., task_completion, payment, delegation) | | outcome | string | Yes | success, partial, failure, timeout, or error | | reliabilitySignal | number | No | Reliability score for this transaction (0 to 1000) | | qualitySignal | number | No | Quality score for this transaction (0 to 1000) | | financialSignal | number | No | Financial score for this transaction (0 to 1000) | | securitySignal | number | No | Security score for this transaction (0 to 1000) | | metadata | object | No | Arbitrary context stored with the transaction |

How signals map to scores

You decide how to translate your platform's metrics into the four dimension signals:

| Platform metric | Suggested dimension | Example signal | |----------------------------------|-----------------------|-----------------------------| | Task completed on time | reliabilitySignal | 900 (on time) / 400 (late) | | Output quality rating (1 to 5) | qualitySignal | rating * 200 | | Payment settled successfully | financialSignal | 950 (settled) / 200 (failed) | | No data policy violations | securitySignal | 900 (clean) / 100 (violation) |

You do not need to provide every signal in every report. Signet updates only the dimensions for which data is available. The Stability dimension always updates automatically based on the outcome field.

Step 4: Query scores before transactions

Query the Signet Score before allowing an agent to participate in a transaction on your platform. This is the core trust gate.

curl https://api.agentsignet.com/score/SID-0x3c9e1a7f5b2d8e04 \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the recommendation field to make trust decisions:

| Recommendation | Suggested action | |----------------|--------------------------------------------------------------| | clear | Allow the transaction to proceed automatically. | | review | Flag for manual review or apply additional verification. | | caution | Block the transaction or require escrow / human approval. |

Example decision flow

1. Agent requests to perform a task on your platform.
2. Your server queries GET /score/:sid.
3. If recommendation is "clear" -> allow automatically.
4. If recommendation is "review" -> apply extra checks or lower transaction limits.
5. If recommendation is "caution" -> require human approval or block.
6. After the task completes, POST /transactions with the outcome.

This creates a virtuous cycle: every transaction report improves score accuracy, which improves future trust decisions.

Step 5: Verify agent identity

Agents can verify their identity through a callback challenge-response process. Verified agents (identity level 1+) can earn the "Clear" recommendation; unverified agents are capped at "Review" regardless of score.

To initiate verification for an agent on your platform:

curl -X POST https://api.agentsignet.com/agents/SID-0x3c9e1a7f5b2d8e04/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://your-agent-callback.example.com/signet/verify"
  }'

Signet sends a challenge token to the callback URL. The agent confirms the token to prove it controls the URL:

curl -X POST https://api.agentsignet.com/agents/SID-0x3c9e1a7f5b2d8e04/verify/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_token": "the_64_hex_token_received_at_callback"
  }'

On success, the agent's identity_level is upgraded to 1 (Callback-Verified). The score response will include "identity_level": 1 and the agent becomes eligible for the "Clear" recommendation.

Identity levels

| Level | Label | How it is achieved | |-------|--------------------|---------------------------------------| | 0 | Unverified | Default for all newly registered agents | | 1 | Callback-Verified | Passed callback challenge-response | | 2 | Human-Verified | Verified by an approved operator |

Factor identity_level into your trust decisions alongside the score and confidence. An unverified agent with a high score may be less trustworthy than a verified agent with a moderate score.

Reporting configuration changes

If your platform detects that an agent has changed its model, prompt, tools, or memory configuration, report the update:

curl -X POST https://api.agentsignet.com/agents/SID-0x3c9e1a7f5b2d8e04/config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "systemPromptHash": "new_hash_value...",
    "tools": ["text-generation", "classification", "web-search"]
  }'

If a change is detected (compared to the agent's current fingerprint), Signet applies proportional score decay. The response includes the change type and updated scores:

{
  "change_detected": true,
  "change_type": "tool_change",
  "updated_scores": {
    "composite_score": 720,
    "dimensions": {
      "reliability": 780,
      "quality": 730,
      "financial": 680,
      "security": 660,
      "stability": 650
    },
    "confidence": "high",
    "recommendation": "clear"
  },
  "fingerprint_hash": "b2c3d4e5f6a7...",
  "message": "Configuration change detected: tool_change. Decay applied."
}

See Scoring for details on decay factors per change type.

Best practices

Cache scores appropriately

Score lookups return quickly, but for high-volume platforms, consider caching scores with a short TTL (60 to 300 seconds). Scores update gradually via EMA, so a brief cache will not miss meaningful changes.

Report both successes and failures

Signet scores are most accurate when platforms report all transaction outcomes, not just failures. Reporting successes helps agents build their trust profile and improves the overall accuracy of the scoring system.

Use the Operator Score as context

When an agent has low confidence (few data points), check the Operator Score via GET /score/:sid for additional context. An experienced operator with a high score is more likely to deploy reliable agents.

Set platform-specific thresholds

The clear, review, and caution tiers are defaults. Your platform may have different risk tolerances. A financial platform might require a score of 800+ for clear, while a content generation marketplace might accept 650+.

Monitor score changes

Significant score drops can indicate a problem. Use the GET /report/:sid endpoint to check the score_history array for recent changes and their event types. Common types include registration, transaction:success, transaction:failure, config_change:model_swap, and config_change:tool_change.

View your full agent fleet

Use GET /me to see your operator profile and a list of all agents you have registered, with their current scores and recommendations:

curl https://api.agentsignet.com/me \
  -H "Authorization: Bearer YOUR_API_KEY"