{"openapi":"3.1.0","info":{"title":"RYCORE API","version":"0.4.1","description":"Risk and security API for autonomous agents on Robinhood Chain (EVM). An agent submits a proposed transaction; RYCORE simulates it, checks it against the active versioned policy, and returns one decision: ALLOW, DENY, or REQUIRE_APPROVAL. The enforced signer (v0.4) holds signer wallets whose private keys never leave the server: POST /v1/transactions/sign produces a signature ONLY for an ALLOWed transaction, or a REQUIRE_APPROVAL transaction carrying a valid one-time Ed25519 approval token from the owner. Plain /v1/transactions/evaluate stays advisory — it returns a decision and cannot stop an agent that ignores it. There is no billing and no token. A web console is served at /console. Policy and key management require an admin key (created with `npm run keygen -- --admin`).","contact":{"name":"RYCORE"}},"servers":[{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"meta","description":"Health and API description"},{"name":"transactions","description":"Evaluate, sign, and list transactions"},{"name":"signers","description":"Enforced-signer wallets (v0.4)"},{"name":"agent","description":"Information about the calling API key"},{"name":"policies","description":"Versioned policy management (writes are admin-only)"},{"name":"keys","description":"API key management (admin-only)"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/health":{"get":{"tags":["meta"],"summary":"Service health","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","required":["ok","service","version"],"properties":{"ok":{"type":"boolean","example":true},"service":{"type":"string","example":"rycore-api"},"version":{"type":"string","example":"0.4.1"}}}}}}}}},"/v1/openapi.json":{"get":{"tags":["meta"],"summary":"This OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1.0 document"}}}},"/v1/agent":{"get":{"tags":["agent"],"summary":"Info about the calling API key","responses":{"200":{"description":"Agent info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInfo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/transactions":{"get":{"tags":["transactions"],"summary":"List evaluations for the calling key, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated evaluations","content":{"application/json":{"schema":{"type":"object","required":["items","total","limit","offset"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Evaluation"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/transactions/evaluate":{"post":{"tags":["transactions"],"summary":"Evaluate a proposed transaction against the agent policy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateRequest"}}}},"responses":{"200":{"description":"Evaluation result (ALLOW, DENY, or REQUIRE_APPROVAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`from` does not match the agent wallet bound to the key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/sign":{"post":{"tags":["transactions"],"summary":"Sign a transaction from a signer wallet (enforced, v0.4)","description":"Runs the evaluate pipeline on the transaction, then signs it with the signer wallet ONLY when the decision is ALLOW — or REQUIRE_APPROVAL with a valid one-time Ed25519 approval token. DENY produces no signature. The `from` address must be a registered, non-revoked signer owned by the calling key’s agent. Nonce and gas are filled from the RPC when omitted; pass the nonce from a 403 APPROVAL_REQUIRED response to keep an approval token valid. With broadcast=true the signed transaction is submitted to the RPC; otherwise only the signed bytes are returned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"responses":{"200":{"description":"Signed transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"DENY (TX_DENIED), missing/invalid/expired/replayed approval (APPROVAL_*), or revoked signer (SIGNER_REVOKED). The body includes the evaluation and, for APPROVAL_REQUIRED, the unsignedTxHash + nonce the owner must approve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown signer wallet (SIGNER_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Signed, but the broadcast was rejected (BROADCAST_FAILED) — the body still contains the signedTx and txHash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Signing unavailable (SIGNER_UNAVAILABLE) or signing failed (SIGNING_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signers":{"get":{"tags":["signers"],"summary":"List signer wallets (own signers; all for admin)","description":"Metadata only — the encrypted key is never returned.","responses":{"200":{"description":"Signer list","content":{"application/json":{"schema":{"type":"object","required":["signers"],"properties":{"signers":{"type":"array","items":{"$ref":"#/components/schemas/Signer"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"Signing is not configured on this server (SIGNER_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["signers"],"summary":"Create a signer wallet for the calling key’s agent","description":"Generates a fresh secp256k1 wallet and an Ed25519 approval keypair. The private key and the approval private key are returned ONCE, in this response only — save them immediately. RYCORE stores only the AES-256-GCM encrypted signer key and the approval public key. Requires the server master key (RYCORE_MASTER_KEY); otherwise 503.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"201":{"description":"Created signer wallet (private keys shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignerCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"Signing is not configured on this server (SIGNER_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signers/{id}/revoke":{"post":{"tags":["signers"],"summary":"Revoke a signer wallet (own signer, or any for admin)","description":"A revoked signer can never sign again. Funds in the wallet are NOT moved — the private key backup still controls them.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Signer revoked","content":{"application/json":{"schema":{"type":"object","required":["revoked","id"],"properties":{"revoked":{"type":"boolean","example":true},"id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No signer with that id (or not owned by the calling key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Signing is not configured on this server (SIGNER_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/policies":{"get":{"tags":["policies"],"summary":"List policy versions, newest first, with the active flag","responses":{"200":{"description":"Policy versions","content":{"application/json":{"schema":{"type":"object","required":["policies"],"properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["policies"],"summary":"Create a new policy version (admin only)","description":"Creates a new immutable version inheriting unspecified fields from the active policy. The new version is created INACTIVE — activate it separately. The approval threshold must be below the max transaction value; a threshold above the max is rejected (it would make the REQUIRE_APPROVAL band unreachable).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyInput"}}}},"responses":{"201":{"description":"Created policy version (inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/policies/{version}":{"get":{"tags":["policies"],"summary":"Get one policy version","parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Policy version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown policy version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/policies/{version}/activate":{"post":{"tags":["policies"],"summary":"Set the active policy version (admin only)","description":"New evaluations use the activated version. Old versions are never modified.","parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Activated policy version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Unknown policy version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys":{"get":{"tags":["keys"],"summary":"List API key metadata (admin only)","description":"Metadata only — secrets and hashes are never returned.","responses":{"200":{"description":"Key metadata list","content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/KeyMetadata"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/keys/{id}/revoke":{"post":{"tags":["keys"],"summary":"Revoke an API key (admin only)","description":"The key id is its prefix (e.g. ryc_test_ab12). Revoked keys get 401 immediately.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked","content":{"application/json":{"schema":{"type":"object","required":["revoked","id"],"properties":{"revoked":{"type":"boolean","example":true},"id":{"type":"string","example":"ryc_test_ab12"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No active key with that id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"A key generated by `npm run keygen`, bound to one agent wallet. Looks like `ryc_test_…`."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The calling key is not an admin key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"AgentInfo":{"type":"object","required":["agent","policyVersion","role","keyPrefix","createdAt"],"properties":{"agent":{"type":"string","description":"Agent wallet address bound to this key"},"policyVersion":{"type":"integer","example":1,"description":"The ACTIVE policy version — the one evaluations use"},"role":{"type":"string","enum":["agent","admin"]},"keyPrefix":{"type":"string","example":"ryc_test_ab12"},"createdAt":{"type":"string","format":"date-time"}}},"PolicyInput":{"type":"object","description":"Fields for a new policy version. Unspecified fields inherit from the active policy. A null USD value disables that cap.","properties":{"maxTxUsd":{"type":["number","null"],"description":"Max USD value of a single transaction. Must be > 0 or null.","example":1000},"maxDailyUsd":{"type":["number","null"],"description":"Max USD spend (ALLOWed txs) per rolling 24h. Must be > 0 or null.","example":5000},"approvalThresholdUsd":{"type":["number","null"],"description":"Above this (and below the max): REQUIRE_APPROVAL. Must be > 0, null, and below maxTxUsd.","example":500},"requireSimulation":{"type":"boolean","example":true},"failClosed":{"type":"boolean","description":"If true, evaluation failures DENY; if false, they REQUIRE_APPROVAL.","example":true},"blockUnlimitedApprovals":{"type":"boolean","description":"If true (default), unlimited approvals are DENIED.","example":true}}},"Policy":{"type":"object","required":["version","risk","security","execution","createdAt","active"],"properties":{"version":{"type":"integer","example":2},"active":{"type":"boolean","description":"Whether this is the version evaluations currently use"},"createdAt":{"type":"string","format":"date-time"},"risk":{"type":"object","properties":{"maxTransactionValueUsd":{"type":["number","null"]},"maxDailySpendUsd":{"type":["number","null"]},"maxPositionSizeUsd":{"type":["number","null"]},"maxSlippageBps":{"type":["number","null"]},"minLiquidityUsd":{"type":["number","null"]}}},"security":{"type":"object","properties":{"allowedContracts":{"type":"array","items":{"type":"string"}},"blockedContracts":{"type":"array","items":{"type":"string"}},"allowedRecipients":{"type":"array","items":{"type":"string"}},"blockedRecipients":{"type":"array","items":{"type":"string"}},"allowedTokens":{"type":"array","items":{"type":"string"}},"blockUnknownRecipients":{"type":"boolean"},"allowUnlimitedApprovals":{"type":"boolean"},"requireSimulation":{"type":"boolean"}}},"execution":{"type":"object","properties":{"requireApprovalAboveUsd":{"type":["number","null"]},"failClosed":{"type":"boolean"},"approvalTtlSecs":{"type":"integer"}}}}},"KeyMetadata":{"type":"object","required":["id","prefix","agent","role","policyVersion","createdAt","revoked","revokedAt"],"description":"Key metadata. Never contains the secret or its hash.","properties":{"id":{"type":"string","description":"Key id = its prefix","example":"ryc_test_ab12"},"prefix":{"type":"string","example":"ryc_test_ab12"},"agent":{"type":"string","description":"Agent wallet address bound to this key"},"role":{"type":"string","enum":["agent","admin"]},"policyVersion":{"type":"integer","example":1},"createdAt":{"type":"string","format":"date-time"},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time"}}},"Signer":{"type":"object","required":["id","address","agent","approvalPublicKey","createdAt","revoked","revokedAt"],"description":"Signer wallet metadata. Never contains the private key or its ciphertext.","properties":{"id":{"type":"string","format":"uuid"},"address":{"type":"string","description":"Signer wallet address"},"agent":{"type":"string","description":"Agent wallet that owns this signer"},"approvalPublicKey":{"type":"string","description":"32-byte Ed25519 approval public key, hex (no 0x prefix)"},"createdAt":{"type":"string","format":"date-time"},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time"}}},"SignerCreated":{"type":"object","required":["id","address","agent","approvalPublicKey","createdAt","revoked","revokedAt","privateKey","approvalPrivateKey","warning"],"description":"Created signer wallet. The two private keys are shown ONCE, in this response only.","properties":{"id":{"type":"string","format":"uuid"},"address":{"type":"string"},"agent":{"type":"string"},"approvalPublicKey":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time"},"privateKey":{"type":"string","description":"Signer wallet private key (0x hex). Shown once — save it now."},"approvalPrivateKey":{"type":"string","description":"Ed25519 approval seed (32 bytes hex, no 0x prefix). Shown once — it signs one-time approval tokens."},"warning":{"type":"string"}}},"SignRequest":{"type":"object","required":["from","to"],"properties":{"chainId":{"type":"integer","description":"Must be 4663 (Robinhood Chain). Defaults to 4663 when omitted.","example":4663},"from":{"type":"string","description":"Signer wallet address — must be a registered, non-revoked signer owned by the calling key’s agent"},"to":{"type":"string","description":"Recipient address"},"value":{"type":"string","description":"Wei as a decimal or 0x hex string. Default \"0\".","example":"10000000000000000"},"data":{"type":"string","description":"Calldata hex. Default \"0x\" (plain transfer).","example":"0x"},"gas":{"type":"string","description":"Gas limit, decimal or 0x hex. When omitted, eth_estimateGas fills it."},"gasPrice":{"type":"string","description":"Gas price in wei, decimal or 0x hex. When omitted, eth_gasPrice fills it."},"nonce":{"type":["integer","string"],"description":"Nonce. When omitted, the pending nonce from RPC fills it. Pass the nonce from a 403 APPROVAL_REQUIRED response to keep an approval token valid."},"broadcast":{"type":"boolean","description":"When true, the signed transaction is submitted to the RPC. Default false (sign only).","example":false},"approval":{"type":"object","description":"One-time Ed25519 approval for a REQUIRE_APPROVAL transaction. The owner signs keccak256(abi.encode(signer, unsignedTxHash, expiry)) with the approval private key; unsignedTxHash = keccak256(abi.encode(from, to, value, keccak256(data), chainId, nonce)).","required":["signature","expiry"],"properties":{"signature":{"type":"string","description":"64-byte Ed25519 signature, 0x + 128 hex chars"},"expiry":{"type":"integer","description":"Unix timestamp (seconds). Must be in the future and within the policy approval TTL."}}},"intent":{"type":"string","description":"Natural-language intent. Stored with the evaluation; not yet verified against the call.","maxLength":2000}}},"SignResponse":{"type":"object","required":["signedTx","txHash","broadcasted","decision","approvedByToken","policyVersion","evaluationId","signer","nonce","gas","gasPrice","chainId"],"properties":{"signedTx":{"type":"string","description":"Signed legacy (type 0) transaction, 0x hex"},"txHash":{"type":"string","description":"keccak256 of the signed tx — the on-chain transaction hash once broadcast"},"broadcasted":{"type":"boolean"},"decision":{"type":"string","enum":["ALLOW","REQUIRE_APPROVAL"]},"approvedByToken":{"type":"boolean","description":"True when the signature was produced under a one-time approval token"},"policyVersion":{"type":"integer","example":1},"evaluationId":{"type":"string","format":"uuid"},"signer":{"type":"string","description":"Signer wallet address"},"nonce":{"type":"integer"},"gas":{"type":"string","description":"Gas limit used, decimal"},"gasPrice":{"type":"string","description":"Gas price in wei, decimal"},"chainId":{"type":"integer","example":4663}}},"EvaluateRequest":{"type":"object","required":["from","to"],"properties":{"chainId":{"type":"integer","description":"Must be 4663 (Robinhood Chain). Defaults to 4663 when omitted.","example":4663},"from":{"type":"string","description":"Sender address — must match the agent wallet bound to the key"},"to":{"type":"string","description":"Recipient address"},"value":{"type":"string","description":"Wei as a decimal or 0x hex string. Default \"0\".","example":"100000000000000000"},"data":{"type":"string","description":"Calldata hex. Default \"0x\" (plain transfer).","example":"0x"},"intent":{"type":"string","description":"Natural-language intent. Stored with the evaluation; not yet verified against the call.","maxLength":2000}}},"Evaluation":{"type":"object","required":["id","decision","reasonCodes","checks","policyVersion","agent","evaluatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"decision":{"type":"string","enum":["ALLOW","DENY","REQUIRE_APPROVAL"]},"reasonCodes":{"type":"array","items":{"type":"string"},"description":"Coded reasons. RISK_*: risk engine. SEC_*: security engine. SYS_*: system conditions (fail-closed).","example":["RISK_MAX_TX_VALUE_EXCEEDED"]},"checks":{"type":"array","items":{"$ref":"#/components/schemas/Check"}},"valueUsd":{"type":["number","null"],"description":"USD value of `value` at evaluation time; null when the price was unavailable"},"valueWei":{"type":"string"},"ethPriceUsd":{"type":["number","null"]},"simulation":{"$ref":"#/components/schemas/Simulation"},"decoded":{"$ref":"#/components/schemas/DecodedCall"},"policyVersion":{"type":"integer","example":1},"agent":{"type":"string"},"evaluatedAt":{"type":"string","format":"date-time"}}},"Check":{"type":"object","required":["id","status","reasonCode","detail","impact"],"properties":{"id":{"type":"string","example":"RISK_MAX_TX_VALUE"},"status":{"type":"string","enum":["PASSED","FAILED","WARNING","UNSUPPORTED","NOT_CONFIGURED","UNCERTAIN"]},"reasonCode":{"type":["string","null"]},"detail":{"type":"string"},"impact":{"type":"string","enum":["DENY","REQUIRE_APPROVAL","NONE"]}}},"Simulation":{"type":"object","required":["success","isContract","revertReason","error","rpcError"],"properties":{"success":{"type":"boolean"},"isContract":{"type":"boolean","description":"Whether `to` has contract code"},"revertReason":{"type":["string","null"],"description":"Set when the call reverted on-chain"},"error":{"type":["string","null"],"description":"Set when the RPC call itself failed or timed out"},"rpcError":{"type":"boolean","description":"True when `error` is an RPC/transport failure (HTTP 429, connection error, timeout) — labelled SYS_RPC_ERROR, never a revert"}}},"DecodedCall":{"type":"object","required":["selector","signature","functionName","isPlainTransfer"],"properties":{"selector":{"type":"string","example":"0x095ea7b3"},"signature":{"type":["string","null"],"example":"approve(address,uint256)"},"functionName":{"type":["string","null"],"example":"approve"},"isPlainTransfer":{"type":"boolean"}}},"Error":{"type":"object","required":["error","message","requestId"],"properties":{"error":{"type":"string","example":"INVALID_API_KEY"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}}