Quickstart Guide

The Signet API lets you register autonomous AI agents, report transaction outcomes, and query trust scores. This guide walks you through your first integration in five steps.

Prerequisites

Before you begin, make sure you have:

• curl or any HTTP client installed
• An agent you want to register (you will need its model provider and model name)

Step 1: Apply for access

Submit an application at agentsignet.com/apply. You will need to provide your name and email. Company and reason are optional but help us review faster.

You can also apply 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",
    "reason": "Building autonomous trading agents"
  }'

Once approved, you will receive an email with your API key.

Step 2: Register your first agent

Your API key follows the format sk_signet_ followed by 64 hex characters. Include it as a Bearer token in the Authorization header of every authenticated request.

Register an agent by sending a POST request to /register:

curl -X POST https://api.agentsignet.com/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-trading-agent",
    "description": "Automated portfolio rebalancing agent",
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "systemPromptHash": "a1b2c3d4...",
    "tools": ["financial-transactions", "data-analysis"]
  }'

The response includes your agent's new SID:

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "name": "my-trading-agent",
  "composite_score": 500,
  "confidence": "low",
  "fingerprint": "e8f9a0b1c2d3e4f5...",
  "message": "Agent registered successfully"
}

Your agent starts with a baseline composite score of 500. The score updates as you report transactions.

Step 3: Report a transaction

After your agent completes a task, report the outcome. Provide dimension signals (0 to 1000) for whichever dimensions are relevant:

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

Response:

{
  "success": true,
  "transaction_id": 1,
  "updated_scores": {
    "composite_score": 530,
    "dimensions": {
      "reliability": 620,
      "quality": 593,
      "financial": 500,
      "security": 500,
      "stability": 590
    },
    "confidence": "low",
    "recommendation": "review"
  },
  "message": "Transaction recorded and scores updated"
}

Step 4: Look up a score

Query an agent's full trust score with GET /score/:sid:

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

Response:

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "agent_name": "my-trading-agent",
  "composite_score": 530,
  "reliability": 620,
  "quality": 593,
  "financial": 500,
  "security": 500,
  "stability": 590,
  "confidence": "low",
  "recommendation": "review",
  "operator": {
    "name": "Alice Smith",
    "score": 500,
    "verified": true
  },
  "config_fingerprint": "e8f9a0b1c2d3e4f5...",
  "last_updated": "2026-02-12T10:30:00.000Z"
}

All dimension scores are integers from 0 to 1000. A newly registered agent will have "confidence": "low" until at least 5 transactions have been reported.

Step 5: Get a full report

The report endpoint returns everything in the score response plus score history, config history, and a transaction summary:

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

Response:

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "agent_name": "my-trading-agent",
  "description": "Automated portfolio rebalancing agent",
  "status": "active",
  "current_score": {
    "composite": 530,
    "reliability": 620,
    "quality": 593,
    "financial": 500,
    "security": 500,
    "stability": 590,
    "confidence": "low",
    "recommendation": "review"
  },
  "operator": {
    "name": "Alice Smith",
    "score": 500,
    "verified": true
  },
  "score_history": [
    {
      "composite": 530,
      "reliability": 620,
      "quality": 593,
      "financial": 500,
      "security": 500,
      "stability": 590,
      "event_type": "transaction:success",
      "timestamp": "2026-02-12T10:35:00.000Z"
    }
  ],
  "config_history": [
    {
      "fingerprint": "e8f9a0b1c2d3e4f5...",
      "model_provider": "openai",
      "model_name": "gpt-4o",
      "change_type": null,
      "timestamp": "2026-02-12T10:30:00.000Z"
    }
  ],
  "transaction_summary": {
    "total": 1,
    "outcomes": {
      "success": 1
    }
  },
  "last_updated": "2026-02-12T10:35:00.000Z"
}

What's next?

• Authentication: Learn about API key security, rate limits, and public endpoints.
• API Reference: Full endpoint documentation with all request and response fields.
• Scoring: Understand how the five-dimension composite score is calculated and updated.
• Integration Guide: End-to-end walkthrough for platforms integrating Signet.