Documentation

Kairo is an API-first smart contract security platform. It produces decisions (ALLOW/WARN/BLOCK) at critical control points: CI, deploy gates, and post-deployment monitoring.

Quickstart

Get Kairo security checks in your CI pipeline in under 5 minutes.

1. Get Your API Key

2. Test the API

bash

curl -X POST https://api.kairoaisec.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "inline",
      "files": [{
        "path": "Token.sol",
        "content": "pragma solidity ^0.8.0; contract Token { ... }"
      }]
    }
  }'

3. Check the Response

json

{
  "decision": "ALLOW",
  "decision_reason": "No security issues detected. Safe to proceed.",
  "risk_score": 0,
  "summary": { "total": 0, "critical": 0, "high": 0, "medium": 0, "low": 0 },
  "ci_annotation": {
    "status": "success",
    "title": "Kairo Security Check Passed"
  }
}

Authentication

All API requests require an API key in the Authorization header.

API Key Format

kairo_sk_live_xxxxx — Production keys

kairo_sk_test_xxxxx — Sandbox keys (coming soon)

Usage

bash

curl -H "Authorization: Bearer kairo_sk_live_xxxxx" ...

Core Concepts

Control Points

Kairo enforces security at four critical control points:

CI/CD

Block unsafe code from merging

Deploy Gate

Final check before mainnet

Monitoring

24/7 surveillance of live contracts

IDE

Real-time feedback (optional)

Decisions

Every API response includes an agentic decision:

Decision	Meaning	CI Action
`ALLOW`	Safe to proceed	Pass
`WARN`	Minor issues, can proceed	Pass (with notes)
`BLOCK`	Critical issues found	Fail
`ESCALATE`	Needs human review	Pending

API Reference

POST/v1/analyze

Analyze smart contract code and return a security decision.

Request Body

json

{
  "source": {
    "type": "inline",
    "files": [{ "path": "Contract.sol", "content": "..." }]
  },
  "config": {
    "severity_threshold": "high",
    "include_suggestions": true
  }
}

POST/v1/deploy/check

Final safety check before deployment. More strict than /analyze.

Request Body

json

{
  "project_id": "proj_xxxxx",
  "contract_name": "Token",
  "network": { "chain_id": 1, "name": "mainnet" }
}

CI Integration

Add Kairo security checks to your GitHub Actions workflow.

yaml

# .github/workflows/security.yml
name: Security Check
on: [pull_request]

jobs:
  kairo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Kairo Security Check
        env:
          KAIRO_API_KEY: ${{ secrets.KAIRO_API_KEY }}
        run: |
          RESPONSE=$(curl -s -X POST https://api.kairoaisec.com/v1/analyze \
            -H "Authorization: Bearer $KAIRO_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{
              \"source\": {
                \"type\": \"inline\",
                \"files\": [{\"path\": \"src/Contract.sol\", \"content\": \"$(cat src/Contract.sol | jq -Rs .)\"}]
              }
            }")

          DECISION=$(echo $RESPONSE | jq -r '.decision')
          echo "Decision: $DECISION"

          if [ "$DECISION" = "BLOCK" ]; then
            echo "::error::Security check failed"
            echo $RESPONSE | jq '.findings'
            exit 1
          fi

Deploy Gate

Add a final safety check before mainnet deployment.

javascript

// deploy.js
async function deploy() {
  // 1. Compile contract
  const compiled = await compile();

  // 2. Check with Kairo before deploying
  const check = await fetch('https://api.kairoaisec.com/v1/deploy/check', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KAIRO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      project_id: process.env.KAIRO_PROJECT_ID,
      contract_name: 'Treasury',
      network: { chain_id: 1, name: 'mainnet' },
    }),
  }).then(r => r.json());

  if (check.decision === 'BLOCK') {
    console.error('Deployment blocked:', check.decision_reason);
    process.exit(1);
  }

  // 3. Proceed with deployment
  const tx = await deployer.deploy(compiled);
  console.log('Deployed:', tx.hash);
}

IDE Integration

The Kairo IDE is an optional client that provides real-time security feedback during development.

What the IDE Provides

• Real-time vulnerability highlighting
• AI-powered auto-fix suggestions
• Pre-deployment safety gate
• Integrated test execution

The IDE is not required for API access. Teams can use the API directly via CI/CD, deploy scripts, or custom tooling.

Need Help?

Questions about integration or API usage?