# Contract Security API

> Compare two caller-supplied EVM bytecodes. Exact and normalized comparisons report hashes, lengths, similarity, and differing byte ranges. No network calls are made.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/contract-security
- Docs: https://www.brainiac.software/api/contract-security/docs
- OpenAPI: https://www.brainiac.software/api/contract-security/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/contract-security/contract-bytecode-compare

$0.05 USDC. 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.

Inputs: reference, candidate, bytecodeKind?, mode?, compilerMetadata?, constructorArguments?, immutableRanges?, expectedDifferences?

Docs: https://www.brainiac.software/api/contract-security/docs#contract-security-contract-bytecode-compare

Example request:

```json
{
  "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
    }
  ]
}
```

Example response:

```json
{
  "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."
  ]
}
```

### POST /api/v1/contract-security/bytecode-structure-diff

$0.04 USDC. 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.

Inputs: left, right

Docs: https://www.brainiac.software/api/contract-security/docs#contract-security-bytecode-structure-diff

Example request:

```json
{
  "left": "0x6001600055",
  "right": "0x6002600055f4"
}
```

Example response:

```json
{
  "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"
    }
  ]
}
```