{"openapi":"3.1.0","info":{"title":"Contract Security API","version":"1.0.0","description":"Compare two caller-supplied EVM bytecodes. Exact and normalized comparisons report hashes, lengths, similarity, and differing byte ranges. No network calls are made. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.\n2. A valid unpaid call returns 402 with the exact amount and payTo.\n3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.\nInclude an Idempotency-Key header of 64 hex characters from 32 random bytes. Reuse that key only for retries of the same operation and request body.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/contract-security/contract-bytecode-compare":{"post":{"operationId":"compare_contract_bytecode","summary":"Compare contract bytecode","description":"Compare two caller-supplied EVM bytecodes. mode exact compares every byte. An omitted mode is exact. mode normalized masks only the supplied immutable ranges and a trailing Solidity CBOR metadata suffix when bytecodeKind is not creation and that suffix is present on both bytecodes. comparison_status is identical, different, partially_comparable, or invalid. Hashes are keccak256 of the supplied bytes. Similarity is the share of equal compared bytes, truncated to 4 decimal places. A difference is not a judgment that either bytecode is malicious, and similar bytecode is not equivalent behavior. No source code is verified and no chain is queried.","tags":["contract-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reference":{"type":"string","maxLength":262146,"pattern":"^0x(?:[0-9a-fA-F]{2})*$"},"candidate":{"type":"string","maxLength":262146,"pattern":"^0x(?:[0-9a-fA-F]{2})*$"},"bytecodeKind":{"type":"string","enum":["runtime","creation"]},"mode":{"type":"string","enum":["exact","normalized"]},"compilerMetadata":{"type":"object","properties":{"compiler":{"type":"string","minLength":1,"maxLength":80},"version":{"type":"string","minLength":1,"maxLength":40}},"additionalProperties":false},"constructorArguments":{"type":"string","maxLength":262146,"pattern":"^0x(?:[0-9a-fA-F]{2})*$"},"immutableRanges":{"maxItems":32,"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"maximum":131072},"end":{"type":"integer","exclusiveMinimum":0,"maximum":131072}},"required":["start","end"],"additionalProperties":false}},"expectedDifferences":{"maxItems":32,"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"maximum":131072},"end":{"type":"integer","exclusiveMinimum":0,"maximum":131072}},"required":["start","end"],"additionalProperties":false}}},"required":["reference","candidate"],"additionalProperties":false},"example":{"reference":"0x6001600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000164736f6c63430008180033","candidate":"0x6002600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000264736f6c634300081a0033","bytecodeKind":"runtime","mode":"normalized","compilerMetadata":{"compiler":"solc","version":"0.8.24"},"immutableRanges":[{"start":5,"end":7}],"expectedDifferences":[{"start":1,"end":2}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"comparison_status":{"type":"string"},"reference_hash":{"type":"string"},"candidate_hash":{"type":"string"},"reference_length":{"type":"number"},"candidate_length":{"type":"number"},"similarity":{"type":"string"},"difference_ranges":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"length":{"type":"number"},"kind":{"type":"string"}},"additionalProperties":true}},"metadata_differences":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reference":{"type":"string"},"candidate":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"comparison_status":"different","reference_hash":"0xc8a324f6d1a8d63a729defc4c20b624f17d7dae1fdf4b5eec5f7c03a54a8da45","candidate_hash":"0xa39f1cb59ec90edd47f46c666deb79f2aef5e485023e84f1586a677d13ff88a0","reference_length":60,"candidate_length":60,"similarity":"80.0000","difference_ranges":[{"start":1,"end":2,"length":1,"kind":"changed"}],"metadata_differences":[{"field":"metadata","reference":"0xa2646970667358220000000000000000000000000000000000000000000000000000000000000000000164736f6c63430008180033","candidate":"0xa2646970667358220000000000000000000000000000000000000000000000000000000000000000000264736f6c634300081a0033","detail":"The compiler metadata suffixes differ."},{"field":"solc","reference":"0.8.24","candidate":"0.8.26","detail":"The metadata suffixes encode different Solidity versions. This is not a source-code verification."},{"field":"compiler","reference":"0.8.24","candidate":"0.8.26","detail":"compilerMetadata.version is 0.8.24. The suffixes encode 0.8.24 and 0.8.26. This was not checked against source code."}],"findings":[{"code":"immutable_ranges_masked","severity":"low","detail":"The supplied immutable ranges were masked before the byte comparison."},{"code":"difference_expected","severity":"low","detail":"The changed bytes at 1:2 fall inside expectedDifferences."},{"code":"bytecode_differs","severity":"medium","detail":"1 unmasked byte ranges differ. A difference is not a judgment that either contract is malicious."},{"code":"metadata_differs","severity":"medium","detail":"The identified compiler metadata differs. This is not a source-code verification."},{"code":"comparison_normalized","severity":"low","detail":"Normalized comparison masked only the supplied immutable ranges and a compiler metadata suffix when that suffix was identified on both bytecodes."}],"limitations":["Hashes are keccak256 of the supplied bytes before any masking.","Similarity is the share of equal compared bytes, truncated to 4 decimal places with integer division. Masked bytes are left out of the count.","A high similarity does not mean the contracts behave the same way.","A difference is not a judgment that either bytecode is malicious.","No source code was verified. Compiler metadata in the request is not a source match.","Normalization masks only caller-supplied immutable ranges and a trailing compiler metadata suffix when bytecodeKind is not creation and the Solidity CBOR pattern is present on both bytecodes.","Other bytecode is not removed. Creation bytecode is not split into init code and runtime code.","Constructor arguments are checked as a suffix only when bytecodeKind is creation and the arguments are supplied.","No chain state was read, and neither bytecode was executed."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/contract-security/bytecode-structure-diff":{"post":{"operationId":"diff_bytecode_structure","summary":"Diff bytecode structure","description":"Decode two caller-supplied EVM bytecodes, or two instruction lists, into opcodes and compare the instruction sequence. Similarity ignores PUSH immediates. The risk delta counts CALL, SSTORE, CREATE, DELEGATECALL, CALLCODE, and SELFDESTRUCT. A high similarity is not proof that the contracts behave the same. No chain is queried.","tags":["contract-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"left":{"anyOf":[{"type":"string","maxLength":200000,"pattern":"^(0x)?[0-9a-fA-F]*$"},{"type":"object","properties":{"ops":{"minItems":1,"maxItems":1500,"type":"array","items":{"type":"object","properties":{"op":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]{0,31}$"},"arg":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]{0,64}$"}},"required":["op"],"additionalProperties":false}}},"required":["ops"],"additionalProperties":false}]},"right":{"anyOf":[{"type":"string","maxLength":200000,"pattern":"^(0x)?[0-9a-fA-F]*$"},{"type":"object","properties":{"ops":{"minItems":1,"maxItems":1500,"type":"array","items":{"type":"object","properties":{"op":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]{0,31}$"},"arg":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]{0,64}$"}},"required":["op"],"additionalProperties":false}}},"required":["ops"],"additionalProperties":false}]}},"required":["left","right"],"additionalProperties":false},"example":{"left":"0x6001600055","right":"0x6002600055f4"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"similarity_index":{"type":"number"},"risk_delta_score":{"type":"number"},"divergence_points":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"left":{"type":"string"},"right":{"type":"string"},"kind":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true},"example":{"similarity_index":86,"risk_delta_score":71,"divergence_points":[{"index":0,"left":"PUSH1 01","right":"PUSH1 02","kind":"immediate"},{"index":3,"left":"3","right":"4","kind":"length"}]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}