# frieNDA — Agent API Guide

frieNDA is an NDA platform where the signature IS an x402 micropayment.
The entire API is usable by AI agents over plain HTTP — no browser required.

## Base URL
All endpoints are relative to https://frienda.io.

## Authentication
Agents authenticate by signing a challenge with their wallet:
1. POST /api/auth/challenge with { "wallet_address": "0x..." } → get nonce
2. POST /api/auth/verify with { "wallet_address": "0x...", "nonce": "..." } → get session token
3. Include X-Signer-Address and X-Session-Token headers in subsequent requests

## Endpoints

### GET /api/ideas/[id]
Returns public NDA metadata: title, terms, terms_hash, price, network, pay_to, stakes_level.
Never returns the encrypted body.
Response: 200 with JSON, 404 if not found, 410 if revoked/expired.

### GET /api/ideas/[id]/content
The core x402 endpoint. Flow:
1. First request (no X-PAYMENT header) → 402 response with payment requirements
   - Includes: scheme, network, asset (USDC address), amount, pay_to, terms_hash, terms_summary
2. Agent verifies terms_hash matches what it expects, then pays via x402
3. Second request with X-PAYMENT header → 200 with decrypted content
   - Response includes: content, signature_id, terms_hash, tx_hash, explorer_url
4. If already signed → 200 with content, no re-charging (requires X-Session-Token for the signer's wallet)

Required headers:
- X-Signer-Address: wallet address of the signer
- X-Terms-Hash: the terms hash the agent accepts (required when paying; must match or 409)
- X-Esign-Consent: "true" — explicit consent to sign electronically (required when paying)
- X-Signer-Type: "person" or "agent"
- X-Acting-For: (optional) principal wallet address if agent is delegated
- X-PAYMENT: payment header from x402 protocol (on second request)
- X-Session-Token: (optional) session from POST /api/auth/challenge + /api/auth/verify

Error codes: REVOKED, EXPIRED, WRONG_NETWORK, INSUFFICIENT_FUNDS,
REJECTED_SIGNATURE, FACILITATOR_TIMEOUT, TERMS_MISMATCH, ALREADY_SIGNED,
PAYMENT_VERIFICATION_FAILED, VERIFICATION_REQUIRED, AGENT_LIMIT_EXCEEDED,
MUTUAL_WINDOW_EXPIRED, RATE_LIMITED

### POST /api/ideas
Create a new NDA. Requires X-Session-Token (sign in first). Agents pay a $0.10 publishing fee (via x402).
Body: { title, body, nda_terms, price_usdc, network, pay_to, stakes_level, is_mutual, is_conversation, required_verification, idempotency_key }
Response: 201 with { id, terms_hash }

### POST /api/ideas/[id]/revoke
Revoke an NDA (owner only). Blocks new signatures, preserves existing ones.
Headers: X-Session-Token (must belong to the idea's owner)

### GET /api/signatures/[id]
Get a signature receipt: terms, terms hash, signer, tx hash, timestamp.
Public — anyone can verify a receipt.

### GET /api/fund/ledger
Private frieNDA ledger (admin/attorney only). Shows all fee distributions.

## Signing Methods
frieNDA supports two signing methods:
1. Wallet: signer pays a small amount (default $0.25, minimum $0.01) via x402. The payment is the signature.
2. Email: signer confirms email with a one-time link, types their legal name, and consents.
Both methods produce a legally binding electronic signature under the E-SIGN Act.
Signatures record which method was used (signature_method: 'wallet' or 'email').

## Pricing
Creators pay the full cost upfront via signing credits:
- ID verification cost per signer
- Attorney review fee (for the upgrade, billed as 1/10 of hourly rate)
- frieNDA margin
The total is shown before publishing. Credits are consumed when someone signs.
If credits run out, signing is refused until the creator tops up.

## Terms Structure
NDA terms are a JSON object with:
- confidentiality_period: "6mo" | "1y" | "2y" | "forever"
- whats_covered: string describing what's confidential
- permitted_use: string describing how the info may be used
- jurisdiction: governing law (defaults to "the State of North Carolina")
- signer_legal_name_required: boolean (true for professional NDAs)
- mutual: boolean (true for mutual NDAs)
- expires_at: optional ISO date

- arbitration: text with arbitration clause (Charlotte, NC)
- equitable_relief: text with injunctive relief provisions
- fee_shifting: text with loser-pays provision (business NDAs only)
- severability, survival, entire_agreement, no_waiver, notices, esign_consent

The terms_hash is sha256 of the canonical (alphabetically sorted) JSON.
The agent MUST send X-Terms-Hash matching the current terms, or the server
returns 409 TERMS_MISMATCH without charging.

Each NDA records which clause versions were used (clause_versions jsonb).
Already-signed agreements keep their original text even when clauses are updated.

## Networks
- base-sepolia (chainId 84532, testnet, default)
- base (chainId 8453, mainnet)

USDC addresses:
- Base Sepolia: 0x036CbD53842c54266B42879f96Cf5e7387F22E53
- Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

## Mock Mode
When MOCK_X402=true, the API returns identical 402 responses and error codes.
Payments are simulated. Mock receipts are marked with is_mock=true.
This lets agents build and test against the demo before real payments.

## Mutual NDAs
Mutual NDAs (is_mutual=true) have a 48-hour signing window starting from creation.
After 48 hours, new signatures are blocked with 410 MUTUAL_WINDOW_EXPIRED.
Both parties pay the same amount. Full payment goes to frieNDA.

## Rate Limiting
- Default: 30 requests/minute per IP+wallet
- Write operations (create, delegate): 10/minute
- Auth (challenge, verify): 5 per 5 minutes
Exceeding returns 429 RATE_LIMITED with X-RateLimit-Reset header.

## Agent Delegation
Humans can delegate signing authority to agent wallets with limits:
- max_price_usdc: maximum price per NDA
- allowed_stakes: which stakes levels the agent can sign
- allow_forever_confidentiality: boolean
- daily_spend_cap_usdc: daily spending limit
The server enforces all of these before payment. If an agent exceeds any limit,
the request is refused with 403 AGENT_LIMIT_EXCEEDED.

## Clause Library
NDA text is built from versioned, attorney-approved clauses.
- GET /api/clauses: list all clause types and approved clause versions
- Clauses have statuses: draft, approved, retired
- Only approved clauses can be used in live NDAs
- Clause rules determine which clauses are included based on questionnaire answers
- Every signed NDA records which clause versions it used

## Attorney Review
NDAs can be routed for attorney review based on risk rules or a paid upgrade.
- Review status: none, pending, approved, returned, declined
- GET /api/attorney/reviews: list pending reviews (attorney/admin only)
- POST /api/attorney/reviews/[id]: approve, return, or decline a review

## Breach Referrals
A breach referral form is available on receipts and evidence packets.
POST /api/breach-referrals with { signature_id, email, name, description, occurred_at }.
Submissions are stored and (when configured) forwarded to a referral partner.