Skip to main content

Developer docs

Seal your first agent action.

Run governed actions through the customer-owned gateway, or use the passive observer when you only need non-blocking event capture.

terminal
# Authority gateway (customer-run enforcement path)
npm install @rankigi/gateway

# Passive observer (non-blocking event capture)
npm install @rankigi/mcp-sidecar

01

Install the SDK

Add RANKIGI to the agent runtime.

02

Wrap one action

Inputs and outputs are hashed, signed, and chained.

03

Export the proof

Download the chain bundle for review.

04

Verify locally

Recompute the chain without trusting RANKIGI.

Quickstart

One wrapped function becomes a receipt.

The SDK is non-blocking. If RANKIGI is unavailable, your agent continues and the SDK records the transport failure.

.env setup
# Enroll an agent and write .env automatically (recommended):
npx @rankigi/cli init

# That writes one credential token, which Rankigi.fromEnv() reads:
RANKIGI_CREDENTIAL=rnk_live_cred_v1...   # API key + agent + passport + signing key
RANKIGI_CHAIN_ID=...                      # optional

# Or set the four variables individually instead of RANKIGI_CREDENTIAL:
RANKIGI_API_KEY=...        # from rankigi.com/dashboard/keys (same key the curl example uses)
RANKIGI_AGENT_ID=...
RANKIGI_PASSPORT_ID=...
RANKIGI_SIGNING_KEY=...
seal-first-event.ts
import "dotenv/config";
import { Rankigi } from "@rankigi/sdk";

const rankigi = Rankigi.fromEnv();

const result = await rankigi.wrap(
  "first-tool-call",
  { tool: "send_email", to: "customer@example.com" },
  async () => {
    return { status: "sent", provider_id: "msg_abc123" };
  },
);

await rankigi.close();
console.log(result);

Verification

Do not trust the dashboard.

Export the chain and recompute it locally. The browser verifier and verify.py are the same product promise in two forms.

Open browser verifier
verify locally
# Export a chain bundle from the dashboard, then verify it locally.
python3 verify.py chain-export.json

# Or paste the sample bundle into:
# https://rankigi.com/verify

Trust model

What RANKIGI proves.

RANKIGI produces scoped evidence for governed operations. The gateway validates a customer-signed Authority Grant, reserves authority before provider dispatch, preserves ambiguous outcomes as indeterminate, and emits a packet that can be checked offline. A passive observer can also record non-blocking events, but observation is not enforcement. Rekor or RFC 3161 anchoring is reported only when the configured adapter returns and its artifact is independently checked.

What it proves: the specific packet checks reported by the verifier, including canonical bytes, signatures, links, and any configured anchor artifact.

What it does not prove:that an agent's reasoning was correct, that an external effect occurred beyond the named provider evidence, or that activity outside the declared capture boundary was absent.

Anchoring: anchoring is an asynchronous, configured capability. Until a provider artifact is returned and verified, the packet must report the anchor as pending or unavailable; a hash or provider inclusion does not prove the underlying action was true or complete.

Post-quantum identity: agent passports use a hybrid Ed25519 + ML-DSA-65 (NIST FIPS 204) signature scheme. New passports are issued with both signatures; when both are present, both must verify -- an invalid post-quantum signature fails the check. Passports issued earlier may carry only the ML-DSA-65 signature or predate signature capture. The ML-DSA-65 signature is verifiable offline with verify.py (via the optional dilithium-py library) or through the API, so post-quantum identity protection does not depend on trusting RANKIGI.

The evidence contract is deliberately narrow: each claim names its source, verification, freshness, and limits instead of collapsing them into a single aggregate status.

API

Use HTTP when an SDK is too much.

The ingest API accepts minimal event metadata and payload hashes. Use the SDK when you need passport signing handled for you.

curl
curl -X POST https://rankigi.com/api/ingest \
  -H "Authorization: Bearer $RANKIGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-uuid",
    "action": "tool_call",
    "tool": "send_email",
    "severity": "info",
    "payload": {
      "input": { "to": "customer@example.com" },
      "output": { "status": "sent" }
    }
  }'
POST
/api/ingest
Submit an event to a chain.
GET
/api/chains/[chainId]/closure-export
Export a closure bundle.
GET
/api/public/revocation
Check passport revocation without auth.
GET
/verify.py
Download the Python reference verifier.