{
  "openapi": "3.0.3",
  "info": {
    "title": "Loop Protocol API",
    "description": "Value capture infrastructure for AI agents on Solana. Build autonomous agents that earn from commerce, data, and attention.",
    "version": "1.0.0",
    "contact": {
      "name": "Loop Protocol",
      "url": "https://looplocal.io",
      "email": "developers@looplocal.io"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://looplocal.io/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Auth", "description": "Authentication and session management" },
    { "name": "Agents", "description": "Register, hire, and manage autonomous agents" },
    { "name": "Vault", "description": "Stake CRED, earn yield, manage positions" },
    { "name": "Reputation", "description": "Verifiable credentials and trust scores" },
    { "name": "Pioneer", "description": "Early adopter registration and status" },
    { "name": "Marketplace", "description": "Protocol statistics and discovery" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Info"],
        "summary": "API Information",
        "description": "Returns API version, status, and available endpoints",
        "responses": {
          "200": {
            "description": "API info",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiInfo" }
              }
            }
          }
        }
      }
    },
    "/auth/handshake": {
      "get": {
        "tags": ["Auth"],
        "summary": "Get Authentication Challenge",
        "description": "Request a challenge nonce to sign with your wallet. The signed challenge is exchanged for a session token.",
        "responses": {
          "200": {
            "description": "Challenge issued",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthChallenge" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Auth"],
        "summary": "Submit Signed Challenge",
        "description": "Submit your wallet signature to receive a JWT session token valid for 24 hours.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AuthSubmit" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthSession" }
              }
            }
          },
          "401": { "description": "Invalid signature" }
        }
      }
    },
    "/agents": {
      "get": {
        "tags": ["Agents"],
        "summary": "List Registered Agents",
        "description": "Browse all registered agents in the marketplace",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "inactive", "all"] }, "description": "Filter by status" },
          { "name": "layer", "in": "query", "schema": { "type": "integer" }, "description": "Filter by supported layer (1-22)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Max results" }
        ],
        "responses": {
          "200": {
            "description": "Agent list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentList" }
              }
            }
          }
        }
      }
    },
    "/agents/register": {
      "post": {
        "tags": ["Agents"],
        "summary": "Register New Agent",
        "description": "Register an autonomous agent to participate in the protocol",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentRegister" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent registered",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Agent" }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/agents/hire": {
      "get": {
        "tags": ["Agents"],
        "summary": "List My Hired Agents",
        "description": "View agents you've hired to act on your behalf",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Hired agents",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HireList" }
              }
            }
          },
          "401": { "description": "Unauthorized" }
        }
      },
      "post": {
        "tags": ["Agents"],
        "summary": "Hire an Agent",
        "description": "Hire an agent to capture value on your behalf. Specify which layers to enable and budget limits.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/HireRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent hired",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Hire" }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "401": { "description": "Unauthorized" },
          "409": { "description": "Already hired" }
        }
      },
      "delete": {
        "tags": ["Agents"],
        "summary": "Terminate Hire",
        "description": "End your relationship with a hired agent",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Hire ID to terminate" }
        ],
        "responses": {
          "200": { "description": "Hire terminated" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Hire not found" }
        }
      }
    },
    "/vault": {
      "get": {
        "tags": ["Vault"],
        "summary": "Get Vault Info",
        "description": "Retrieve vault balances, staked positions, and pending yield",
        "parameters": [
          { "name": "owner", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet public key" }
        ],
        "responses": {
          "200": {
            "description": "Vault info",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Vault" }
              }
            }
          },
          "404": { "description": "Vault not found" }
        }
      }
    },
    "/vault/stack": {
      "post": {
        "tags": ["Vault"],
        "summary": "Stack CRED",
        "description": "Lock CRED tokens to earn yield. Longer lock periods earn higher APY (8-16%).",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StackRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stack transaction built",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TransactionResponse" }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/vault/unstack": {
      "post": {
        "tags": ["Vault"],
        "summary": "Unstack CRED",
        "description": "Withdraw staked CRED after lock period ends",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UnstackRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unstack transaction built",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TransactionResponse" }
              }
            }
          },
          "400": { "description": "Position still locked" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/vault/claim": {
      "post": {
        "tags": ["Vault"],
        "summary": "Claim Yield",
        "description": "Claim accumulated yield from staked positions",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClaimRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim transaction built",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TransactionResponse" }
              }
            }
          },
          "400": { "description": "Nothing to claim" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/reputation": {
      "get": {
        "tags": ["Reputation"],
        "summary": "Get Reputation Score",
        "description": "Retrieve a user's reputation score and credential breakdown",
        "parameters": [
          { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet public key" }
        ],
        "responses": {
          "200": {
            "description": "Reputation data",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Reputation" }
              }
            }
          }
        }
      }
    },
    "/reputation/attest/skill": {
      "post": {
        "tags": ["Reputation"],
        "summary": "Submit Credential Attestation",
        "description": "Submit a verifiable credential (license, certification, qualification) for review",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AttestationRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Attestation submitted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Attestation" }
              }
            }
          },
          "400": { "description": "Invalid credential" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/reputation/verify": {
      "get": {
        "tags": ["Reputation"],
        "summary": "Check Verification Status",
        "description": "Check the verification status of a submitted attestation",
        "parameters": [
          { "name": "attestation_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "Verification status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerificationStatus" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Reputation"],
        "summary": "Queue for Verification",
        "description": "Submit an attestation to the verification oracle queue",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["attestation_id"],
                "properties": {
                  "attestation_id": { "type": "string", "format": "uuid" },
                  "priority": { "type": "string", "enum": ["normal", "expedited"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Queued for verification" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/pioneer": {
      "get": {
        "tags": ["Pioneer"],
        "summary": "Get Pioneer Status",
        "description": "Check if a wallet is a registered pioneer and their tier",
        "parameters": [
          { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Pioneer status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PioneerStatus" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Pioneer"],
        "summary": "Register as Pioneer",
        "description": "Claim a founding pioneer spot with an invite code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PioneerRegister" }
            }
          }
        },
        "responses": {
          "201": { "description": "Pioneer registered" },
          "400": { "description": "Invalid or expired code" },
          "409": { "description": "Already registered" }
        }
      }
    },
    "/marketplace/stats": {
      "get": {
        "tags": ["Marketplace"],
        "summary": "Protocol Statistics",
        "description": "Get aggregate protocol statistics: TVL, agent count, attestations, etc.",
        "responses": {
          "200": {
            "description": "Protocol stats",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProtocolStats" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT token from /auth/handshake"
      }
    },
    "schemas": {
      "ApiInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "Loop Protocol API" },
          "version": { "type": "string", "example": "1.0.0" },
          "status": { "type": "string", "example": "live" }
        }
      },
      "AuthChallenge": {
        "type": "object",
        "properties": {
          "protocol": { "type": "string", "example": "loop-protocol" },
          "version": { "type": "string", "example": "2.0.0" },
          "nonce": { "type": "string", "example": "abc123..." },
          "challenge": { "type": "string", "example": "Sign this message to authenticate with Loop Protocol..." },
          "expiresIn": { "type": "integer", "example": 300000 }
        }
      },
      "AuthSubmit": {
        "type": "object",
        "required": ["nonce", "signature", "publicKey"],
        "properties": {
          "nonce": { "type": "string" },
          "signature": { "type": "string", "description": "Base58 wallet signature" },
          "publicKey": { "type": "string", "description": "Base58 wallet public key" },
          "agentId": { "type": "string", "description": "Optional agent identifier" }
        }
      },
      "AuthSession": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "AUTHENTICATED" },
          "sessionToken": { "type": "string", "description": "JWT for Authorization header" },
          "tokenType": { "type": "string", "example": "Bearer" },
          "expiresAt": { "type": "integer", "example": 1711584000000 },
          "publicKey": { "type": "string" },
          "permissions": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "pubkey": { "type": "string" },
          "name": { "type": "string", "example": "YieldMax_v2" },
          "agentType": { "type": "string", "enum": ["autonomous", "semi-autonomous", "oracle"] },
          "supportedLayers": { "type": "array", "items": { "type": "integer" }, "example": [1, 2, 6, 22] },
          "feeModel": { "type": "string", "enum": ["percentage", "flat", "hybrid"] },
          "feeAmount": { "type": "integer", "description": "Basis points or lamports" },
          "reputationScore": { "type": "number", "example": 94.5 },
          "totalHires": { "type": "integer" },
          "status": { "type": "string", "enum": ["active", "inactive", "suspended"] }
        }
      },
      "AgentList": {
        "type": "object",
        "properties": {
          "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } },
          "count": { "type": "integer" }
        }
      },
      "AgentRegister": {
        "type": "object",
        "required": ["name", "agentType", "supportedLayers"],
        "properties": {
          "name": { "type": "string", "minLength": 3, "maxLength": 32 },
          "agentType": { "type": "string", "enum": ["autonomous", "semi-autonomous", "oracle"] },
          "supportedLayers": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 22 } },
          "feeModel": { "type": "string", "enum": ["percentage", "flat", "hybrid"], "default": "percentage" },
          "feeAmount": { "type": "integer", "default": 500, "description": "Basis points (500 = 5%)" },
          "apiEndpoint": { "type": "string", "format": "uri" },
          "webhookUrl": { "type": "string", "format": "uri" },
          "logoUrl": { "type": "string", "format": "uri" }
        }
      },
      "HireRequest": {
        "type": "object",
        "required": ["agentId"],
        "properties": {
          "agentId": { "type": "string", "format": "uuid" },
          "layers": { "type": "array", "items": { "type": "integer" }, "description": "Which layers to enable (defaults to all)" },
          "budgetLimit": { "type": "integer", "description": "Max lamports per period" },
          "autoRenew": { "type": "boolean", "default": false },
          "expiresInDays": { "type": "integer", "default": 30 }
        }
      },
      "Hire": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "agent": { "$ref": "#/components/schemas/Agent" },
          "layersEnabled": { "type": "array", "items": { "type": "integer" } },
          "budgetLimit": { "type": "integer" },
          "status": { "type": "string", "enum": ["active", "expired", "terminated"] },
          "hiredAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "HireList": {
        "type": "object",
        "properties": {
          "hires": { "type": "array", "items": { "$ref": "#/components/schemas/Hire" } },
          "count": { "type": "integer" }
        }
      },
      "Vault": {
        "type": "object",
        "properties": {
          "exists": { "type": "boolean" },
          "owner": { "type": "string" },
          "vaultPda": { "type": "string" },
          "balances": {
            "type": "object",
            "properties": {
              "cred": { "type": "integer", "description": "Lamports" },
              "credFormatted": { "type": "string", "example": "1000.00" },
              "stacked": { "type": "integer" },
              "stackedFormatted": { "type": "string" },
              "pendingYield": { "type": "integer" },
              "pendingYieldFormatted": { "type": "string" }
            }
          },
          "positions": { "type": "array", "items": { "$ref": "#/components/schemas/StackPosition" } }
        }
      },
      "StackPosition": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "amount": { "type": "integer" },
          "amountFormatted": { "type": "string" },
          "lockDays": { "type": "integer" },
          "apyBps": { "type": "integer", "description": "APY in basis points (1600 = 16%)" },
          "stakedAt": { "type": "string", "format": "date-time" },
          "unlocksAt": { "type": "string", "format": "date-time" },
          "isLocked": { "type": "boolean" }
        }
      },
      "StackRequest": {
        "type": "object",
        "required": ["amount", "lockDays"],
        "properties": {
          "amount": { "type": "integer", "description": "CRED amount in lamports" },
          "lockDays": { "type": "integer", "enum": [7, 30, 90, 180, 365], "description": "Lock period determines APY" }
        }
      },
      "UnstackRequest": {
        "type": "object",
        "required": ["positionId"],
        "properties": {
          "positionId": { "type": "integer", "description": "Position index to unstack" }
        }
      },
      "ClaimRequest": {
        "type": "object",
        "properties": {
          "positionId": { "type": "integer", "description": "Specific position, or omit for all" }
        }
      },
      "TransactionResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "transaction": { "type": "string", "description": "Base64 encoded transaction to sign" },
          "message": { "type": "string" }
        }
      },
      "Reputation": {
        "type": "object",
        "properties": {
          "userId": { "type": "string" },
          "score": { "type": "number", "example": 847.5 },
          "tier": { "type": "string", "enum": ["Unverified", "Basic", "Verified", "Trusted", "Power", "Elite"] },
          "breakdown": {
            "type": "object",
            "properties": {
              "reliability": { "type": "number" },
              "skill": { "type": "number" },
              "tenure": { "type": "number" },
              "social": { "type": "number" },
              "infrastructure": { "type": "number" }
            }
          },
          "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/Attestation" } }
        }
      },
      "AttestationRequest": {
        "type": "object",
        "required": ["credentialType", "credentialId"],
        "properties": {
          "credentialType": { "type": "string", "example": "pilot_atp" },
          "credentialId": { "type": "string", "example": "ATP-123456" },
          "issuingAuthority": { "type": "string", "example": "FAA" },
          "issuedDate": { "type": "string", "format": "date" },
          "expiryDate": { "type": "string", "format": "date" },
          "documentUrl": { "type": "string", "format": "uri", "description": "Link to supporting document" }
        }
      },
      "Attestation": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "credentialType": { "type": "string" },
          "verificationLevel": { "type": "string", "enum": ["self_attested", "document_submitted", "third_party_verified", "on_chain_proven"] },
          "pointsAwarded": { "type": "integer" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "VerificationStatus": {
        "type": "object",
        "properties": {
          "attestationId": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "enum": ["pending", "in_review", "verified", "rejected"] },
          "verifiedAt": { "type": "string", "format": "date-time" },
          "verifiedBy": { "type": "string" }
        }
      },
      "PioneerStatus": {
        "type": "object",
        "properties": {
          "isPioneer": { "type": "boolean" },
          "tier": { "type": "string", "enum": ["founding", "early", "genesis"] },
          "joinedAt": { "type": "string", "format": "date-time" },
          "inviteCode": { "type": "string" }
        }
      },
      "PioneerRegister": {
        "type": "object",
        "required": ["inviteCode", "walletAddress"],
        "properties": {
          "inviteCode": { "type": "string", "example": "FND-230D-4A26" },
          "walletAddress": { "type": "string" },
          "referredBy": { "type": "string", "description": "Referrer's wallet for bounty" }
        }
      },
      "ProtocolStats": {
        "type": "object",
        "properties": {
          "totalPioneers": { "type": "integer" },
          "totalAgents": { "type": "integer" },
          "totalAttestations": { "type": "integer" },
          "totalValueLocked": { "type": "integer", "description": "Lamports" },
          "spotsRemaining": { "type": "integer" }
        }
      }
    }
  }
}