Documentation — Unykorn Legal

Overview

Unykorn Legal is the world's first Web3 legal namespace platform. It combines Stellar-anchored legal identity namespaces (.law, .legal, .ai, .x402), x402 payment rails on Apostle Chain 7332, AI-powered case analysis, and JusticeChain evidence anchoring into a unified platform for legal professionals and their clients.

Unykorn Legal is built on three open protocols:

Stellar Mainnet — Namespace ownership records, identity anchoring
Apostle Chain 7332 — x402 payment settlement, subscription billing, JusticeChain evidence hashes
ULegal AI — Legal case analysis engine trained on millions of public court filings, statutes, and legal precedents

💡Unykorn Legal is a platform for legal information and tools. It is not a law firm and does not provide legal advice. AI outputs should be reviewed by a licensed attorney before any legal action.

Quickstart

Get your .law namespace registered and receive your first x402 payment in under 5 minutes.

1. Install the SDK

npm install @unykorn/legal-sdk

2. Initialize the Client

import { ULegalClient } from '@unykorn/legal-sdk';

const client = new ULegalClient({
  apiKey: 'ulegal_...',        // from legal.unykorn.org/dashboard
  stellarKeypair: keypair,  // Stellar keypair for namespace signing
  apostleUrl: 'http://localhost:7332',
  chainId: 7332
});

3. Register Your Namespace

const result = await client.namespaces.register({
  name: 'yourname',
  tld: '.law',           // .law | .legal | .ai | .x402
  years: 1,
  paymentAgent: agentId  // your Apostle Chain agent ID
});

console.log(result.namespace);  // "yourname.law"
console.log(result.txHash);     // on-chain transaction hash
console.log(result.stellarTx);  // Stellar record hash

4. Accept x402 Payments

// Create an x402 payable endpoint
const invoice = await client.x402.createInvoice({
  to: 'yourname.law',
  amount: '15000000000000000000',  // 15 ATP (18 decimals)
  asset: 'ATP',
  description: '30-minute legal consultation',
  expiresIn: 3600  // seconds
});

console.log(invoice.payUrl);   // shareable payment link
console.log(invoice.status);   // "pending"

Authentication

The Unykorn Legal API uses API key authentication for server-side calls and Stellar keypair signing for namespace operations.

Method	Use Case
`Authorization: Bearer ulegal_...`	All REST API calls
Stellar Ed25519 signature	Namespace registration & transfers
Apostle Chain agent key	x402 payment signing

⚠Never expose your API key or Stellar secret key in client-side code. Use environment variables and server-side signing.

Namespace System

Unykorn Legal namespaces are Stellar Mainnet records that establish a legal identity on the Web3 layer. A namespace like smith.law is a payment address, a signing identity, a verified credential anchor, and an x402 endpoint — all in one.

Namespace Format

// Format: {name}.{tld}
smith.law          // attorney identity
acmecorp.legal     // law firm identity
casebot.ai         // AI legal service
payme.x402         // payment-only endpoint

Namespace Properties

Property	Type	Description
`name`	string	The label portion before the TLD
`tld`	string	.law \| .legal \| .ai \| .x402
`owner`	StellarPublicKey	Stellar address owning this namespace
`apostleAgent`	UUID	Linked Apostle Chain agent for x402 receipt
`registered`	ISO 8601	Registration timestamp
`expires`	ISO 8601	Expiry date (annual renewal required)
`stellarHash`	64-char hex	Stellar ledger transaction hash

Stellar Registration

Namespaces are registered on Stellar Mainnet using a manage_data operation. The data key is ulegal:{tld}:{name} and the value is a JSON metadata payload signed by the owner's keypair.

// Stellar manage_data format
{
  "key": "ulegal:.law:smith",
  "value": {
    "owner": "GBYLA6VHX4UWI...",
    "apostleAgent": "550e8400-e29b-41d4-a716-446655440000",
    "registeredAt": "2026-07-01T00:00:00Z",
    "barNumber": "CA-123456",        // optional
    "jurisdiction": "California",       // optional
    "sig": "ed25519:abc123..."        // owner keypair signature
  }
}

TLD Reference

TLD	Purpose	Annual Price	Min. Length
`.law`	Licensed attorney identity	49 ATP	3 chars
`.legal`	Law firms and legal entities	39 ATP	3 chars
`.ai`	AI legal tools and assistants	59 ATP	2 chars
`.x402`	x402 payment-only endpoints	29 ATP	3 chars

x402 Integration

x402 is the AI-to-AI payment protocol on Apostle Chain 7332. For legal applications, it enables instant ATP payments for consultations, case reviews, document services, and monthly subscriptions — with no payment processor, no chargebacks, and on-chain receipts.

How x402 Works

Client sends ATP to a namespace address (e.g., smith.law)
Apostle Chain nodes route the payment to the attorney's agent ID
A receipt is generated at POST /v1/tx with type: "transfer"
Both parties get a signed receipt hash they can reference in any dispute

Payment Flows

One-Time Consultation Payment

// POST http://apostle-chain:7332/v1/tx
{
  "hash": "a1b2c3d4...",      // 64-char hex, no 0x
  "from": "client-agent-uuid",
  "nonce": 1,
  "chain_id": 7332,
  "payload": {
    "type": "transfer",
    "to": "attorney-agent-uuid",
    "asset": "ATP",
    "amount": "15000000000000000000"  // 15 ATP as string
  },
  "signature": "128-char-hex-sig",
  "timestamp": "2026-07-01T12:00:00Z"
}

💡All amount fields must be sent as strings in JSON (not numbers). JavaScript's JSON.stringify loses precision on large integers. Use "15000000000000000000" not 15000000000000000000.

Subscription Billing

Monthly subscriptions are managed by smart contract on Apostle Chain. The contract auto-debits the client's agent balance on the renewal date and emits a SUBSCRIPTION_RENEWED event you can listen to via webhook.

const sub = await client.billing.createSubscription({
  clientAgentId: 'client-uuid',
  plan: 'attorney-pro',
  "billingPeriod": 'monthly',    // or 'annual'
  atpAmount: '49000000000000000000'  // 49 ATP
});

Case Review API

The AI Case Review API accepts a case type and facts, and returns a structured legal analysis including: key issues, strengths, weaknesses, document requirements, and a strategy checklist.

Endpoint	Method	Description
`/v1/review/analyze`	POST	Run full case analysis
`/v1/review/{id}`	GET	Retrieve stored review
`/v1/review/{id}/anchor`	POST	Anchor review to JusticeChain
`/v1/review/types`	GET	List available case types

Request: Analyze a Case

// POST /v1/review/analyze
{
  "caseType": "criminal",  // criminal|injury|family|immigration|corporate|realestate|employment|estate
  "jurisdiction": "California",
  "facts": "Client was stopped at a DUI checkpoint on July 1, 2026...",
  "requesterId": "client-uuid",
  "includeDocumentChecklist": true,
  "includeStrategyChecklist": true,
  "includeTimeline": true
}

Response

{
  "id": "rev_8f2a9b...",
  "caseType": "criminal",
  "summary": "DUI first offense, probable cause for stop is contestable...",
  "keyIssues": ["Validity of checkpoint", "Field sobriety test procedures"],
  "strengths": ["No prior record", "Checkpoint legality question"],
  "weaknesses": ["BAC reading above 0.08", "Video footage exists"],
  "documentChecklist": ["Arrest report", "BAC test results", "Dashcam footage"],
  "strategyChecklist": ["Challenge checkpoint procedures", "Request all evidence"],
  "timeline": [{ "phase": "Arraignment", "eta": "72 hours" }],
  "createdAt": "2026-07-01T12:00:00Z",
  "anchoredToChain": false
}

Evidence Anchoring

JusticeChain anchoring commits the SHA-256 hash of any document or case review to Apostle Chain 7332. The block timestamp becomes an immutable proof of when you possessed that information.

const anchor = await client.justice.anchorDocument({
  documentHash: sha256(documentBuffer),  // 32-byte hash
  label: 'DUI Case Review — Smith v. State 2026',
  signerAgentId: agentId,
  atpFee: '2000000000000000000'  // 2 ATP anchoring fee
});

console.log(anchor.txHash);    // on-chain transaction
console.log(anchor.blockHeight); // block number
console.log(anchor.timestamp);  // block timestamp (immutable)

AI Assistant

The ULegal AI Assistant is a context-aware legal assistant trained on U.S. federal and state statutes, regulations, and public court opinions. It can answer legal research questions, explain statutes, and provide procedural guidance.

⚠The AI does not know confidential client facts by default. Each session is isolated. Explicitly pass sessionId to maintain context across calls.

// POST /v1/ai/chat
{
  "sessionId": "sess_abc123",  // optional, for context continuity
  "message": "What is the statute of limitations for personal injury in California?",
  "jurisdiction": "California",     // optional, improves accuracy
  "caseContext": "rev_8f2a9b..."     // optional, link to a case review
}

REST API Reference

Base URL

https://api.legal.unykorn.org/v1

Rate Limits

Plan	Requests / min	AI Reviews / month
Starter (Free)	30	3
Attorney Pro	120	Unlimited
Law Firm	500	Unlimited
Enterprise	Custom	Unlimited

Error Codes

Code	Meaning
`401`	Missing or invalid API key
`402`	Payment required (x402 — insufficient ATP balance)
`403`	Feature not available on current plan
`422`	Invalid request body (see error.details)
`429`	Rate limit exceeded
`503`	JusticeChain or Apostle Chain node unavailable

Webhooks

// Webhook event types
namespace.registered      // new namespace on Stellar
namespace.expiring        // 30 days before expiry
payment.received          // x402 payment settled
payment.failed            // payment rejected
subscription.renewed      // monthly billing successful
subscription.cancelled    // client cancelled
review.anchored           // case review hash committed to chain
partner.connected         // new client-attorney connection

JavaScript SDK

npm install @unykorn/legal-sdk # Or with yarn yarn add @unykorn/legal-sdk

Key Modules

client.namespaces — Register, transfer, resolve, list namespaces
client.x402 — Create invoices, watch payments, subscription management
client.review — Run AI case analysis, anchor to JusticeChain
client.justice — Direct JusticeChain anchoring and verification
client.ai — Chat sessions with ULegal AI assistant
client.partners — Browse attorneys, initiate x402 connection requests

Python SDK

pip install unykorn-legal

from unykorn_legal import ULegalClient

client = ULegalClient(
    api_key="ulegal_...",
    apostle_url="http://localhost:7332",
    chain_id=7332
)

# Run a case review
review = client.review.analyze(
    case_type="criminal",
    jurisdiction="California",
    facts="Client charged with DUI first offense..."
)
print(review['summary'])

Smart Contract Templates

Unykorn Legal provides Apostle Chain smart contract templates for common legal engagements. Templates are deployed by the attorney and customized per-engagement.

Template	Use Case	Fee
`RetainerAgreement`	Attorney retainer with monthly ATP billing	1 ATP to deploy
`ContingencyFee`	Personal injury — auto-disburse on settlement	1 ATP to deploy
`EscrowDispute`	Neutral escrow for disputed payments	0.5 ATP
`NDAEnforcement`	NDA + breach penalty smart contract	1 ATP to deploy
`EstateTrust`	Programmable trust distribution schedule	2 ATP to deploy

💡Smart contract templates are available on the Attorney Pro plan and above. Enterprise clients can build custom contract logic using the ULegal Contract SDK.

Need Help?

Our developer team is available via Discord, email, and on-chain support ticket (50 ATP response SLA).

Discord Email Dev Team