{ "openapi": "3.1.0", "info": { "title": "SIMA Agent Discovery API", "version": "0.8.0", "description": "SIMA agent API documentation. Wallet identity and AI-native protection purchase flow are published here. Commercial insurance amounts are always denominated in the protected contract asset. Official timing (BM-001 / BM-001A): Quote Validity = 30 seconds; Payment Window = 30 seconds after quote acceptance; Protection Window = 5 minutes after premium payment; Certificate Lifetime = 24 hours from issuance; Claim Window = 24 hours from issuance; Historical Record = permanent." }, "servers": [ { "url": "https://api.sima-prime.com", "description": "Future SIMA production API" } ], "tags": [ { "name": "Agent Discovery", "description": "Wallet-first agent identity endpoints plus planned protection API contracts." }, { "name": "Agent Purchase", "description": "AI-native protection offer and purchase flow. All commercial amounts are denominated in the protected contract asset only." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/agent/wallet/nonce": { "post": { "summary": "Prepare wallet authentication challenge", "description": "Available wallet-first identity endpoint. Prepares a wallet authentication challenge for a human, bot, or AI agent wallet.", "operationId": "createAgentWalletNonce", "tags": [ "Agent Discovery" ], "x-sima-status": "available", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletNonceRequest" } } } }, "responses": { "200": { "description": "Planned response shape for a wallet challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletNonceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/agent/wallet/verify": { "post": { "summary": "Verify wallet ownership", "description": "Available wallet-first identity endpoint. Verifies wallet ownership using a signed challenge and returns the normal SIMA accessToken / refreshToken model.", "operationId": "verifyAgentWallet", "tags": [ "Agent Discovery" ], "x-sima-status": "available", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletVerifyRequest" } } } }, "responses": { "200": { "description": "Planned response shape for wallet verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletVerifyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/protection/offer": { "post": { "summary": "Get protection offer", "description": "Returns commercial insurance terms only: protection availability, premium, coverage, maximum net payment, certificate duration, coverage window, and purchase availability. All amounts are denominated in the protected contract asset. Does not provide investment advice, risk scores, purchase recommendations, or fiat or alternate currency values. Does not create a Quote entity, certificate, or payment intent. Commercial insurance begins only after POST /agent/protection/purchase with protectionDecision PURCHASE_PROTECTION.", "operationId": "getAgentProtectionOffer", "tags": [ "Agent Purchase" ], "x-sima-status": "available", "x-sima-ai-native-contract": true, "x-sima-issues-certificate": false, "x-sima-creates-quote": false, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProtectionCommercialRequest" } } } }, "responses": { "200": { "description": "Protection offer with commercial insurance terms only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProtectionOfferResponse" }, "example": { "contractVersion": "SIMA_AGENT_PROTECTION_OFFER_V1", "offerId": "00000000-0000-4000-8000-000000000001", "asset": "SOL", "protectionAvailable": true, "purchaseAvailable": true, "purchaseMode": "PRESERVE_TRADE_SIZE", "totalBudget": null, "recommendedTradeAmount": "1000", "protectedAmount": "1000", "premiumAmount": "50", "totalCost": "1050", "coverageAmount": "500", "deductibleAmount": "100", "maximumNetPayment": "400", "rulesVersion": "SIMA_V1_50_5_10_40", "quoteValiditySeconds": 30, "coverageWindowMinutes": 5, "certificateLifetimeHours": 24, "claimWindowHours": 24, "purchaseEndpoint": "POST /agent/protection/purchase", "budgetGuidance": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/protection/purchase": { "post": { "summary": "Purchase or decline protection after protection offer", "description": "Commercial insurance gate. PURCHASE_PROTECTION creates a persisted quote, protection request, and PENDING_PAYMENT certificate via production ProtectionService. DECLINE_PROTECTION logs the outcome only — no quote, certificate, or payment.", "operationId": "purchaseAgentProtection", "tags": [ "Agent Purchase" ], "x-sima-status": "available", "x-sima-ai-native-contract": true, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AgentProtectionCommercialRequest" }, { "type": "object", "required": [ "protectionDecision" ], "properties": { "protectionDecision": { "type": "string", "enum": [ "PURCHASE_PROTECTION", "DECLINE_PROTECTION" ] }, "offerId": { "type": "string", "format": "uuid" } } } ] } } } }, "responses": { "200": { "description": "PURCHASE_PROTECTION creates quote and PENDING_PAYMENT certificate; DECLINE_PROTECTION creates nothing commercial.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AgentProtectionPurchaseAcceptedResponse" }, { "$ref": "#/components/schemas/AgentProtectionPurchaseDeclinedResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/protection/certificates/{id}/payment-intent": { "get": { "summary": "Get RPC-bound premium payment intent", "description": "Delegates to the production ProtectionPremiumPaymentService payment intent for the certificate. Returns SOL treasury instructions for programmatic wallet signing.", "operationId": "getAgentProtectionPaymentIntent", "tags": [ "Agent Purchase" ], "x-sima-status": "available", "x-sima-ai-native-contract": true, "x-sima-verifies-payment": false, "x-sima-issues-certificate": false, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SOL payment intent bound to certificate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProtectionPaymentIntentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/protection/certificates/{id}/confirm-payment": { "post": { "summary": "Confirm premium payment with RPC verification", "description": "Delegates to POST /protection/certificates/:id/confirm-premium-payment. Verifies on-chain SOL payment and activates the certificate to ACTIVE when valid.", "operationId": "confirmAgentProtectionPayment", "tags": [ "Agent Purchase" ], "x-sima-status": "available", "x-sima-ai-native-contract": true, "x-sima-verifies-payment": true, "x-sima-issues-certificate": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentReference", "transactionSignature" ], "properties": { "paymentReference": { "type": "string" }, "transactionSignature": { "type": "string" } } } } } }, "responses": { "200": { "description": "Certificate ACTIVE after RPC verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProtectionActivationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/protection/certificates/{id}": { "get": { "summary": "Get protection certificate by id", "description": "Returns the production protection certificate record for the authenticated agent account.", "operationId": "getAgentProtectionCertificate", "tags": [ "Agent Purchase" ], "x-sima-status": "available", "x-sima-ai-native-contract": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Protection certificate record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProtectionCertificateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "NotImplemented": { "description": "Not implemented in this milestone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "planned", "message": "This agent endpoint is documented for future capability and is not implemented in this milestone." } } } }, "BadRequest": { "description": "Invalid request body or wallet authentication message mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Invalid, expired, missing, or consumed wallet authentication challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Record not found or not owned by the authenticated wallet account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "WalletNonceRequest": { "type": "object", "required": [ "walletAddress", "chain" ], "properties": { "walletAddress": { "type": "string", "description": "Wallet address for the human, bot, or AI agent wallet." }, "chain": { "type": "string", "enum": [ "ETHEREUM", "BASE", "BSC", "SOLANA" ] }, "agentId": { "type": "string", "description": "Optional agent or automation system identifier." } }, "additionalProperties": false }, "WalletNonceResponse": { "type": "object", "required": [ "walletAddress", "chain", "message", "nonce", "expiresAt", "status" ], "properties": { "walletAddress": { "type": "string" }, "chain": { "type": "string" }, "message": { "type": "string", "description": "Challenge message to sign." }, "nonce": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "available" } }, "additionalProperties": false }, "WalletVerifyRequest": { "type": "object", "required": [ "walletAddress", "chain", "message", "signature" ], "properties": { "walletAddress": { "type": "string" }, "chain": { "type": "string", "enum": [ "ETHEREUM", "BASE", "BSC", "SOLANA" ] }, "message": { "type": "string" }, "signature": { "type": "string" } }, "additionalProperties": false }, "WalletVerifyResponse": { "type": "object", "required": [ "accessToken", "refreshToken", "user" ], "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "user": { "$ref": "#/components/schemas/AgentWalletUser" } }, "additionalProperties": false }, "AgentWalletUser": { "type": "object", "required": [ "id", "email", "firstName", "lastName", "role", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "description": "Wallet-created users use the normal customer role. Agent wallet auth does not accept caller-controlled role assignment.", "example": "customer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentProtectionCommercialRequest": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "chain", "walletAddress", "assetAddress", "assetType" ], "properties": { "chain": { "type": "string", "enum": [ "ETHEREUM", "BASE", "BSC", "SOLANA" ] }, "walletAddress": { "type": "string" }, "assetAddress": { "type": "string" }, "assetSymbol": { "type": "string" }, "assetType": { "type": "string", "enum": [ "TOKEN", "NFT", "MEMECOIN", "NEW_LAUNCH" ] }, "purchaseMode": { "type": "string", "enum": [ "PRESERVE_TRADE_SIZE", "WITHIN_TOTAL_BUDGET" ], "default": "PRESERVE_TRADE_SIZE", "description": "Optional purchase calculation mode. Defaults to PRESERVE_TRADE_SIZE when omitted." }, "totalBudget": { "type": "string", "description": "Required when purchaseMode is WITHIN_TOTAL_BUDGET. Maximum total spend (trade + premium) denominated in the contract asset.", "example": "1" }, "protectedAmount": { "type": "string", "description": "Required when purchaseMode is PRESERVE_TRADE_SIZE (default). Protected trade amount denominated in the contract asset (SOL on Solana). Decimal string greater than zero.", "example": "1000" } }, "additionalProperties": false }, "AgentProtectionOfferResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "contractVersion", "offerId", "asset", "protectionAvailable", "purchaseAvailable", "purchaseMode", "recommendedTradeAmount", "protectedAmount", "premiumAmount", "totalCost", "coverageAmount", "deductibleAmount", "maximumNetPayment", "rulesVersion", "quoteValiditySeconds", "coverageWindowMinutes", "certificateLifetimeHours", "claimWindowHours" ], "properties": { "contractVersion": { "type": "string", "const": "SIMA_AGENT_PROTECTION_OFFER_V1" }, "offerId": { "type": "string", "format": "uuid" }, "asset": { "type": "string", "example": "SOL" }, "protectionAvailable": { "type": "boolean" }, "purchaseAvailable": { "type": "boolean" }, "purchaseMode": { "type": "string", "enum": [ "PRESERVE_TRADE_SIZE", "WITHIN_TOTAL_BUDGET" ], "example": "PRESERVE_TRADE_SIZE" }, "totalBudget": { "type": [ "string", "null" ], "description": "Present when purchaseMode is WITHIN_TOTAL_BUDGET.", "example": "1" }, "recommendedTradeAmount": { "type": "string", "description": "Maximum protectable trade amount for the selected purchase mode.", "example": "1000" }, "protectedAmount": { "type": "string", "example": "1000" }, "premiumAmount": { "type": "string", "example": "50" }, "totalCost": { "type": "string", "description": "Trade amount plus premium in the contract asset.", "example": "1050" }, "coverageAmount": { "type": "string", "example": "500" }, "deductibleAmount": { "type": "string", "example": "100" }, "maximumNetPayment": { "type": "string", "example": "400" }, "rulesVersion": { "type": "string", "const": "SIMA_V1_50_5_10_40" }, "quoteValiditySeconds": { "type": "integer", "example": 30 }, "coverageWindowMinutes": { "type": "integer", "example": 5 }, "certificateLifetimeHours": { "type": "integer", "example": 24 }, "claimWindowHours": { "type": "integer", "example": 24 }, "purchaseEndpoint": { "type": "string", "example": "POST /agent/protection/purchase" }, "budgetGuidance": { "type": [ "string", "null" ], "description": "Commercial calculation guidance when purchaseMode is WITHIN_TOTAL_BUDGET. Not investment advice." }, "terms": { "type": "array", "items": { "type": "string" } }, "disclaimer": { "type": "string" } }, "additionalProperties": false }, "AgentProtectionPurchaseAcceptedResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "protectionDecision", "quoteId", "requestId", "certificateId", "certificateStatus", "paymentIntentEndpoint", "confirmPaymentEndpoint", "paymentWindowEndAt", "paymentWindowSeconds", "disclaimer" ], "properties": { "protectionDecision": { "type": "string", "const": "PURCHASE_PROTECTION" }, "offerId": { "type": [ "string", "null" ], "format": "uuid" }, "quoteId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "certificateId": { "type": "string", "format": "uuid" }, "certificateStatus": { "type": "string", "const": "PENDING_PAYMENT" }, "paymentIntentEndpoint": { "type": "string", "example": "GET /agent/protection/certificates/{id}/payment-intent" }, "confirmPaymentEndpoint": { "type": "string", "example": "POST /agent/protection/certificates/{id}/confirm-payment" }, "paymentWindowEndAt": { "type": "string", "format": "date-time" }, "paymentWindowSeconds": { "type": "integer", "example": 30 }, "disclaimer": { "type": "string" } }, "additionalProperties": false }, "AgentProtectionPurchaseDeclinedResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "protectionDecision", "quoteCreated", "protectionCreated", "certificateId", "disclaimer" ], "properties": { "protectionDecision": { "type": "string", "const": "DECLINE_PROTECTION" }, "offerId": { "type": [ "string", "null" ], "format": "uuid" }, "quoteCreated": { "type": "boolean", "const": false }, "protectionCreated": { "type": "boolean", "const": false }, "certificateId": { "type": "null" }, "disclaimer": { "type": "string" } }, "additionalProperties": false }, "AgentProtectionPaymentIntentResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "certificateId", "chain", "asset", "paymentAsset", "senderWalletAddress", "destinationTreasuryWalletAddress", "amountDue", "amountDueLamports", "paymentReference", "paymentWindowEndAt", "paymentWindowSeconds", "protectedAmount", "premiumAmount", "status" ], "properties": { "certificateId": { "type": "string", "format": "uuid" }, "chain": { "type": "string", "const": "SOLANA" }, "asset": { "type": "string", "const": "SOL" }, "paymentAsset": { "type": "string", "const": "SOL" }, "senderWalletAddress": { "type": "string" }, "destinationTreasuryWalletAddress": { "type": "string" }, "amountDue": { "type": "string", "example": "50" }, "amountDueLamports": { "type": "string" }, "paymentReference": { "type": "string" }, "paymentWindowEndAt": { "type": "string", "format": "date-time" }, "paymentWindowSeconds": { "type": "integer", "example": 30 }, "protectedAmount": { "type": "string", "example": "1000" }, "premiumAmount": { "type": "string", "example": "50" }, "status": { "type": "string", "const": "PENDING_PAYMENT" } }, "additionalProperties": false }, "AgentProtectionActivationResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "certificateId", "certificateNumber", "certificateStatus", "coverageStatus", "claimEligibilityStatus", "asset", "assetSymbol", "protectedAmount", "premiumAmount", "coverageAmount", "deductibleAmount", "premiumPaidAt", "coverageStartAt", "coverageEndAt", "protectionWindowEndAt", "certificateLifetimeEndAt", "claimWindowEndAt", "transactionSignature", "paymentReference", "idempotentReplay" ], "properties": { "certificateId": { "type": "string", "format": "uuid" }, "certificateNumber": { "type": "string" }, "certificateStatus": { "type": "string", "const": "ACTIVE" }, "coverageStatus": { "type": "string", "const": "ACTIVE" }, "claimEligibilityStatus": { "type": "string", "const": "ELIGIBLE" }, "asset": { "type": "string", "const": "SOL" }, "assetSymbol": { "type": "string" }, "protectedAmount": { "type": "string" }, "premiumAmount": { "type": "string" }, "coverageAmount": { "type": "string" }, "deductibleAmount": { "type": "string" }, "premiumPaidAt": { "type": "string", "format": "date-time" }, "coverageStartAt": { "type": "string", "format": "date-time" }, "coverageEndAt": { "type": "string", "format": "date-time" }, "protectionWindowEndAt": { "type": "string", "format": "date-time" }, "certificateLifetimeEndAt": { "type": "string", "format": "date-time" }, "claimWindowEndAt": { "type": "string", "format": "date-time" }, "transactionSignature": { "type": "string" }, "paymentReference": { "type": "string" }, "idempotentReplay": { "type": "boolean" } }, "additionalProperties": false }, "AgentProtectionCertificateResponse": { "type": "object", "x-sima-ai-native-contract": true, "required": [ "id", "certificateNumber", "certificateStatus", "chain", "asset", "assetSymbol", "protectedAmount", "premiumAmount", "coverageAmount", "deductibleAmount", "maximumNetPayment", "coverageWindowMinutes", "rulesVersion" ], "properties": { "id": { "type": "string", "format": "uuid" }, "certificateNumber": { "type": "string" }, "certificateStatus": { "type": "string" }, "chain": { "type": "string", "const": "SOLANA" }, "asset": { "type": "string", "const": "SOL" }, "assetSymbol": { "type": "string" }, "protectedAmount": { "type": "string" }, "premiumAmount": { "type": "string" }, "coverageAmount": { "type": "string" }, "deductibleAmount": { "type": "string" }, "maximumNetPayment": { "type": "string" }, "coverageWindowMinutes": { "type": "integer", "example": 5 }, "certificateLifetimeEndAt": { "type": [ "string", "null" ], "format": "date-time" }, "claimWindowEndAt": { "type": [ "string", "null" ], "format": "date-time" }, "coverageStartAt": { "type": [ "string", "null" ], "format": "date-time" }, "coverageEndAt": { "type": [ "string", "null" ], "format": "date-time" }, "premiumPaidAt": { "type": [ "string", "null" ], "format": "date-time" }, "rulesVersion": { "type": "string", "const": "SIMA_V1_50_5_10_40" } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false } } }, "x-sima-discovery-status": "wallet-identity-available", "x-sima-agent-wallet-identity-implemented": true, "x-sima-agent-protection-purchase-flow-implemented": true, "x-sima-agent-protection-purchase-flow-path": "/agent/protection/offer -> /agent/protection/purchase -> /agent/protection/certificates/{id}/payment-intent -> /agent/protection/certificates/{id}/confirm-payment", "x-sima-agent-protection-purchase-flow-delegates-to": "ProtectionService + ProtectionPremiumPaymentService", "x-sima-agent-protection-purchase-flow-verifies-payment": true, "x-sima-agent-protection-purchase-flow-issues-certificate": true, "x-sima-agent-protection-purchase-flow-requires-explicit-acceptance": true, "x-sima-agent-protection-purchase-flow-mcp-execution": false, "x-sima-protection-model": "Protection availability is broad. SIMA does not approve, score, audit, endorse, certify, or validate assets before protection issuance. A certificate gives the right to submit a claim and receive investigation. Evidence review, claim decisions, treasury review, and payout execution are separate later steps." }