API

אימות גישה

יש לשלוח את המפתח כ־bearer token בכל קריאה. מפתחות מוצגים פעם אחת בעת היצירה; אנו שומרים רק גיבוב (hash).

Authorization: Bearer signet_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

כתובת בסיס: https://basignet.com/api/v1. תיאור קריא למכונה זמין ב־/api/v1/openapi.json.

יצירת בקשה

curl https://basignet.com/api/v1/requests \
  -H "Authorization: Bearer $SIGNET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "targetAddress": "TNeiUDQmrGHbsC4oPd8L6dZdxyPQrrWyP2",
    "reference": "KYC-2026-0412",
    "anchor": true,
    "messageLocale": "ru",
    "expiresAt": "2026-10-31T23:59:59Z"
  }'

רק chain הוא שדה חובה. השארת targetAddress ריק מאפשרת לצד שכנגד לספק את הכתובת שבה הוא חותם; הגדרתו מחייבת חתימה בכתובת זו בדיוק.

anchor: true מעגן את התעודה על השרשרת לאחר החתימה, והעיגון נספר במכסה החודשית באותו רגע. messageLocale קובע את שפת הודעת ברירת המחדל (פירוט בסעיף בלוקצ׳יינים ושפות); message מחליף את גוף ההודעה בטקסט מותאם. הכותרת התחתונה Nonce / Issued / Domain מתווספת תמיד.

התגובה היא אובייקט הבקשה. יש לשלוח את signingUrl לצד שכנגד בערוץ התקשורת של הגורם המבקש.

שליפת בקשה

curl https://basignet.com/api/v1/requests/{token} \
  -H "Authorization: Bearer $SIGNET_KEY"

מחזיר את אובייקט הבקשה. status הוא pending, failed (החתימה האחרונה לא אומתה; הקישור נשאר שמיש), verified או expired. לאחר האימות, השדה certificate מתמלא.

רשימת בקשות

curl "https://basignet.com/api/v1/requests?status=verified&limit=50" \
  -H "Authorization: Bearer $SIGNET_KEY"

{ "object": "list", "data": [ …requests ], "hasMore": true, "nextBefore": "2026-09-30T10:12:03.117Z" }

החדשות ביותר קודם. limit בין 1 ל־100 (ברירת מחדל 20), status מסנן, ו־before מקבל את ערך nextBefore של העמוד הקודם.

תעודה

curl https://basignet.com/api/v1/requests/{token}/certificate \
  -H "Authorization: Bearer $SIGNET_KEY" -o proof.json

curl "https://basignet.com/api/v1/requests/{token}/certificate?format=pdf" \
  -H "Authorization: Bearer $SIGNET_KEY" -o certificate.pdf

חבילת ההוכחה העצמאית כ־JSON, או כ־PDF עם ?format=pdf. התשובה היא 409 עד שהבקשה נחתמת. ניתן לאמת את החבילה בלעדינו, באמצעות כלי האימות בקוד פתוח.

בלוקצ׳יינים ושפות

curl https://basignet.com/api/v1/chains

ציבורי, ללא צורך במפתח: הבלוקצ׳יינים הנתמכים (ה־id משמש כערך chain) והשפות הזמינות עבור messageLocale.

וובהוקים

הגדרת נקודת קצה תחת חשבון → וובהוקים מאפשרת לקבל HTTPS POST במקום תשאול חוזר:

• request.verified: הצד שכנגד חתם והתעודה הונפקה.
• request.anchored: התעודה עוגנה על השרשרת (רק לבקשות שנוצרו עם anchor).
• ping: אירוע הבדיקה מדף החשבון.

גוף הבקשה הוא { id, type, created, data: { request } }, כאשר request הוא אותו אובייקט שה־API מחזיר. יש להשיב בכל קוד 2xx תוך 5 שניות. מסירות שנכשלו נשלחות שוב לאחר דקה, 5 דקות, 30 דקות, 2, 6, 12 ו־24 שעות, ולאחר מכן מסומנות כנכשלות. יש להשתמש ב־id כדי להתעלם מכפילויות.

כל POST כולל Signet-Signature: t=…,v1=…: v1 הוא HMAC-SHA256 בקידוד hex של t + "." + raw body עם סוד החתימה של נקודת הקצה. יש לבדוק אותו על הגוף הגולמי, לפני הפענוח, ולדחות חותמות זמן ישנות מכמה דקות:

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

function verifySignet(rawBody, header, secret, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

# Python
import hmac, hashlib, time

def verify_signet(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1 or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

שגיאות ומגבלות

HTTP/1.1 403
{ "error": { "type": "plan_required", "message": "API access is included in the Pro and Business plans." } }

שגיאות מוחזרות כ־JSON: { "error": { "type", "message" } }. סוגים: unauthorized (401), plan_required (403), not_found (404, גם עבור טוקן של חשבון אחר), conflict (409), invalid_request (400), rate_limited (429, עם Retry-After).

כל מפתח יכול לבצע 120 קריאות בדקה.

אובייקט הבקשה

{
  "object": "request",
  "token": "q0tHA2UW6oiuuzVC1qtIf2N1dgKX6miW",
  "status": "verified",                      // pending | failed | verified | expired
  "chain": "ethereum",
  "chainLabel": "Ethereum",
  "targetAddress": null,                     // null = supplied by the signer
  "reference": "KYC-2026-0412",
  "anchor": true,
  "signingUrl": "https://basignet.com/s/q0tHA2UW6oiuuzVC1qtIf2N1dgKX6miW",
  "challenge": "BA Signet — Proof of Wallet Control\n…\nNonce: …\nIssued: …\nDomain: basignet.com",
  "createdAt": "2026-09-30T09:58:41.201Z",
  "expiresAt": null,
  "completedAt": "2026-09-30T10:03:12.554Z",
  "certificate": {                           // null until signed
    "address": "0x5e3fbf618ef1cc1cc021e7fed95e07c6ff334ca8",
    "sigType": "eip191",
    "contentHash": "0xaa00c6f6…",
    "verifiedAt": "2026-09-30T10:03:12.554Z",
    "verifyUrl": "https://basignet.com/verify/0xaa00c6f6…",
    "anchorStatus": "anchored",              // unanchored | pending | anchored
    "anchor": {                              // null until anchored
      "chain": "polygon",
      "txHash": "0x…",
      "txUrl": "https://polygonscan.com/tx/0x…",
      "blockNumber": 94660444,
      "blockTime": "2026-09-29T15:30:06.000Z",
      "merkleRoot": "0x…",
      "bitcoinBlockHeight": null
    }
  }
}

ייתכן שיתווספו שדות במסגרת v1; שדות קיימים אינם משנים שם ואינם מוסרים.