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 receive real-time score update notifications.

How platforms integrate Signet

What does a Signet integration look like? A typical integration follows four phases: operator registration, agent registration, transaction reporting, and pre-transaction score queries. Webhooks provide an optional fifth layer for real-time notifications.

The flow looks like this:

  1. You register as an operator 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: Register as an operator

What is an operator? An operator is the human or organization that controls one or more agents. Operator registration creates your account and issues your API key.

Contact the Signet team or join the waitlist to register as an operator. Once approved, you receive:

  • An operator ID tied to your account
  • An API key in the format sk_signet_ + 32 hex characters
  • Access to the Signet dashboard for monitoring your agents

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

When should I register an agent? 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 sk_signet_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-alpha-7",
    "description": "Customer support triage agent",
    "model": "claude-sonnet",
    "capabilities": ["text-generation", "classification"]
  }'

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

Bulk registration

If you are migrating an existing fleet of agents, contact the Signet team for bulk registration support. Bulk registration accepts a JSON array of agent objects and returns SIDs for each.

Step 3: Report transactions

How does Signet learn about agent behavior? 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 or transaction on your platform, send a transaction report:

curl -X POST https://api.agentsignet.com/transactions \
  -H "Authorization: Bearer sk_signet_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
    "type": "task_completion",
    "outcome": "success",
    "metrics": {
      "completion_time_ms": 1200,
      "quality_rating": 0.92,
      "payment_status": "settled"
    },
    "timestamp": "2025-07-20T14:12:00Z"
  }'

Transaction fields

| Field | Type | Required | Description | |-------------|--------|----------|----------------------------------------------------| | sid | string | Yes | The agent's Signet ID | | type | string | Yes | Transaction type (e.g., task_completion, payment, delegation) | | outcome | string | Yes | success, failure, partial, or disputed | | metrics | object | No | Dimension-relevant metrics (see below) | | timestamp | string | Yes | ISO 8601 timestamp of the transaction |

Metrics mapping

Different metrics feed into different score dimensions:

| Metric | Feeds into | Description | |--------------------|--------------|--------------------------------------------| | completion_time_ms | Reliability | How quickly the task was completed | | task_completed | Reliability | Boolean indicating task completion | | quality_rating | Quality | 0.0 to 1.0 quality assessment | | error_count | Quality | Number of errors during execution | | payment_status | Financial | settled, pending, failed, disputed | | data_handling | Security | compliant, violation |

You do not need to provide every metric in every report. Signet updates only the dimensions for which data is available.

Step 4: Query scores before transactions

When should I query an agent's score? 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-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c \
  -H "Authorization: Bearer sk_signet_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

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.

Best practices

Cache scores appropriately

Score lookups return in under 50ms, 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 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 /report/:sid endpoint to check the score_history array for recent changes and their reasons. Common reasons include config_change_decay, transaction_update, and time_decay.

Webhook integration

How do I get notified about score changes? Signet supports webhooks that push real-time notifications to your server when an agent's score changes significantly.

Setting up webhooks

Register a webhook endpoint in the Signet dashboard or via the management API:

curl -X POST https://api.agentsignet.com/webhooks \
  -H "Authorization: Bearer sk_signet_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-platform.com/webhooks/signet",
    "events": ["score.changed", "score.threshold_crossed", "config.changed"],
    "secret": "whsec_your_webhook_secret"
  }'

Webhook events

| Event | Trigger | |--------------------------|-------------------------------------------------------------| | score.changed | Agent score updated by more than 20 points | | score.threshold_crossed| Agent crossed a recommendation tier boundary | | config.changed | Agent configuration change detected | | score.dormant | Agent flagged as dormant due to extended inactivity |

Webhook payload

{
  "event": "score.threshold_crossed",
  "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "previous_score": 710,
  "current_score": 685,
  "previous_recommendation": "clear",
  "current_recommendation": "review",
  "reason": "transaction_update",
  "timestamp": "2025-07-20T14:12:00Z"
}

Verifying webhook signatures

Every webhook request includes a Signet-Signature header containing an HMAC-SHA256 signature. Verify it against the secret you provided during registration to ensure the request is authentic:

Signet-Signature: sha256=5d41402abc4b2a76b9719d911017c592

Compute the HMAC of the raw request body using your webhook secret and compare it to the signature value. Reject any request where the signatures do not match.

Know which agents to trust.

Join the waitlist for early access to Signet scores, reports, and the API.

No spam. Unsubscribe anytime.