Probity Wallet Reputation

Screen an Ethereum address or `.eth` ENS name for on-chain reputation risk. Costs 1 credit. Returns a signed reputation score (-100 to +100), a risk band, a confidence level, a sanctioned flag, the top evidence factors, a screeningId, and a link to the full report. The enhanced review is generated in the background. Fetch it with get_screening_narrative(screeningId). Use the score, band, and sanctioned flag to gate pre-trade or payout flows.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Ethereum address (0x...) or `.eth` ENS name (e.g. vitalik.eth) to screen. ENS names resolve to their current mainnet address and must resolve or the call errors. Addresses are case-insensitive and need not be checksummed."
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "screeningId": {
      "type": "string",
      "description": "Immutable identifier for this screen (rsr_...)"
    },
    "address": {
      "type": "string",
      "description": "The screened address"
    },
    "score": {
      "type": "number",
      "description": "Signed reputation score from -100 to +100. Lower is worse."
    },
    "bandCode": {
      "type": "string",
      "description": "Band identifier, e.g. LOW_RISK, REPUTABLE"
    },
    "band": {
      "type": "string",
      "description": "Reputation band, e.g. Low Risk, Reputable"
    },
    "confidence": {
      "type": "string",
      "enum": [
        "High",
        "Medium",
        "Low"
      ],
      "description": "Engine confidence in the result"
    },
    "sanctioned": {
      "type": "boolean",
      "description": "True if the address is a direct OFAC match"
    },
    "transactionCount": {
      "type": "integer",
      "description": "Number of transactions analysed"
    },
    "summary": {
      "type": "string",
      "description": "One line verdict headline"
    },
    "evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable code for this signal, e.g. OUTBOUND_DUST_SPRAY"
          },
          "factor": {
            "type": "string",
            "description": "Category of the signal, e.g. Behaviour Patterns"
          },
          "severity": {
            "type": "string",
            "enum": [
              "High",
              "Medium",
              "Low"
            ]
          },
          "message": {
            "type": "string",
            "description": "Short description of the signal"
          }
        },
        "required": [
          "code",
          "factor",
          "severity",
          "message"
        ],
        "additionalProperties": false
      },
      "description": "Up to 10 signals behind the verdict, most severe first"
    },
    "screenedAt": {
      "type": "string",
      "description": "When the screen ran (ISO-8601)"
    },
    "reportUrl": {
      "type": "string",
      "description": "Link to the full report on the Probity dashboard"
    }
  },
  "required": [
    "screeningId",
    "address",
    "score",
    "bandCode",
    "band",
    "confidence",
    "sanctioned",
    "transactionCount",
    "summary",
    "evidence",
    "screenedAt",
    "reportUrl"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Retrieve the enhanced Probity review for a completed screen by its screeningId. Costs zero credits. Returns the narrative and the key concerns it raises. It is generated in the background after screen_address returns, so it may briefly be pending. Retry shortly if so.

{
  "type": "object",
  "properties": {
    "screeningId": {
      "type": "string",
      "description": "The rsr_... id returned by screen_address. Must reference a completed screen; the narrative can be pending for a few seconds right after the screen returns."
    }
  },
  "required": [
    "screeningId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "screeningId": {
      "type": "string",
      "description": "The screen this review belongs to"
    },
    "address": {
      "type": "string",
      "description": "The screened address"
    },
    "narrative": {
      "type": "string",
      "description": "The enhanced review text"
    },
    "concerns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Key concerns raised by the review"
    },
    "reportUrl": {
      "type": "string",
      "description": "Link to the full report on the Probity dashboard"
    }
  },
  "required": [
    "screeningId",
    "address",
    "narrative",
    "concerns",
    "reportUrl"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Retrieve the authenticated user's prior screening runs for a specific Ethereum address, each with the same detail as screen_address: reputation score, band, confidence, sanctioned flag, and the top evidence signals. Use it to recall context for an already-screened address. Costs zero credits, unlike screen_address which always runs a fresh screen. For runs across all your addresses, use get_screening_history.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Ethereum address (0x...) or .eth ENS name to look up historic screenings for"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Number of past runs to return (1-50, default 5, newest first)"
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "screeningId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Immutable run id (rsr_...)"
          },
          "address": {
            "type": "string",
            "description": "The screened address"
          },
          "ensName": {
            "type": [
              "string",
              "null"
            ],
            "description": "ENS name for the address, when known"
          },
          "score": {
            "type": "number",
            "description": "Signed reputation score from -100 to +100. Lower is worse."
          },
          "bandCode": {
            "type": "string",
            "description": "Band identifier, e.g. LOW_RISK"
          },
          "band": {
            "type": "string",
            "description": "Reputation band, e.g. Low Risk"
          },
          "confidence": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "High",
                  "Medium",
                  "Low"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Engine confidence for this run"
          },
          "sanctioned": {
            "type": "boolean",
            "description": "True if the address is a direct OFAC match"
          },
          "transactionCount": {
            "type": "integer",
            "description": "Number of transactions analysed"
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "factor": {
                  "type": "string"
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "High",
                    "Medium",
                    "Low"
                  ]
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "factor",
                "severity",
                "message"
              ],
              "additionalProperties": false
            },
            "description": "Up to 10 signals behind this run, most severe first"
          },
          "screenedAt": {
            "type": "string",
            "description": "When the screen ran (ISO-8601)"
          },
          "reportUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Link to the full report on the Probity dashboard"
          }
        },
        "required": [
          "screeningId",
          "address",
          "ensName",
          "score",
          "bandCode",
          "band",
          "confidence",
          "sanctioned",
          "transactionCount",
          "evidence",
          "screenedAt",
          "reportUrl"
        ],
        "additionalProperties": false
      },
      "description": "Recent screening runs, newest first, each with the same detail as screen_address"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compare two completed screens by their screeningId and see what changed. Costs zero credits. Two runs of the same address show why the reputation score moved. Two different addresses show a side by side. Returns each run score, band, and confidence, a reason level diff, and the score change broken into its drivers. Small differences between runs of one address can be normal variation rather than a data change.

{
  "type": "object",
  "properties": {
    "runIdA": {
      "type": "string",
      "description": "First screeningId (rsr_...). Must be a completed screen you own."
    },
    "runIdB": {
      "type": "string",
      "description": "Second screeningId (rsr_...). Must be a completed screen you own."
    }
  },
  "required": [
    "runIdA",
    "runIdB"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "temporal_delta",
        "side_by_side"
      ],
      "description": "temporal_delta when both runs are the same address, else side_by_side"
    },
    "scoreDelta": {
      "type": "number",
      "description": "runA score minus runB score"
    },
    "runA": {
      "type": "object",
      "properties": {
        "screeningId": {
          "type": "string",
          "description": "The rsr_... id of this run"
        },
        "address": {
          "type": "string",
          "description": "The screened address"
        },
        "ensName": {
          "type": [
            "string",
            "null"
          ],
          "description": "ENS name for the address, when known"
        },
        "score": {
          "type": "number",
          "description": "Signed reputation score from -100 to +100. Lower is worse."
        },
        "bandCode": {
          "type": "string",
          "description": "Band identifier, e.g. LOW_RISK"
        },
        "band": {
          "type": "string",
          "description": "Reputation band, e.g. Low Risk"
        },
        "confidence": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "High",
                "Medium",
                "Low"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Engine confidence for this run"
        },
        "transactionCount": {
          "type": "integer",
          "description": "Number of transactions analysed"
        },
        "screenedAt": {
          "type": "string",
          "description": "When this screen ran (ISO-8601)"
        },
        "reportUrl": {
          "type": "string",
          "description": "Link to the full report on the Probity dashboard"
        }
      },
      "required": [
        "screeningId",
        "address",
        "ensName",
        "score",
        "bandCode",
        "band",
        "confidence",
        "transactionCount",
        "screenedAt",
        "reportUrl"
      ],
      "additionalProperties": false
    },
    "runB": {
      "$ref": "#/properties/runA"
    },
    "reasonDiff": {
      "type": "object",
      "properties": {
        "added": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "factor": {
                "type": "string"
              },
              "severity": {
                "$ref": "#/properties/runA/properties/confidence/anyOf/0"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "factor",
              "severity",
              "message"
            ],
            "additionalProperties": false
          },
          "description": "Reasons present in runA but not runB"
        },
        "removed": {
          "type": "array",
          "items": {
            "$ref": "#/properties/reasonDiff/properties/added/items"
          },
          "description": "Reasons present in runB but not runA"
        },
        "changed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "factor": {
                "type": "string"
              },
              "from": {
                "$ref": "#/properties/runA/properties/confidence/anyOf/0"
              },
              "to": {
                "$ref": "#/properties/runA/properties/confidence/anyOf/0"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "factor",
              "from",
              "to",
              "message"
            ],
            "additionalProperties": false
          },
          "description": "Reasons in both runs whose severity changed from runB to runA"
        }
      },
      "required": [
        "added",
        "removed",
        "changed"
      ],
      "additionalProperties": false,
      "description": "What changed between the two runs at the reason level"
    },
    "compositionDiff": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "side": {
            "type": "string",
            "enum": [
              "raising",
              "lowering"
            ]
          },
          "change": {
            "type": "string",
            "enum": [
              "appeared",
              "strengthened",
              "weakened",
              "removed"
            ]
          },
          "widthPctA": {
            "type": "number"
          },
          "widthPctB": {
            "type": "number"
          }
        },
        "required": [
          "group",
          "label",
          "side",
          "change",
          "widthPctA",
          "widthPctB"
        ],
        "additionalProperties": false
      },
      "description": "Which score drivers differ between the runs"
    }
  },
  "required": [
    "mode",
    "scoreDelta",
    "runA",
    "runB",
    "reasonDiff",
    "compositionDiff"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the authenticated user's most recent screening runs across all addresses, newest first, each with the same detail as screen_address: score, band, confidence, sanctioned flag, and the top evidence signals. Returns up to `limit` runs (default 20), so raise `limit` to reach older runs. Costs zero credits. For the history of one specific address, use get_address_screening_history instead.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Number of results (1-100, default 20)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "screeningId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Immutable run id (rsr_...)"
          },
          "address": {
            "type": "string",
            "description": "The screened address"
          },
          "ensName": {
            "type": [
              "string",
              "null"
            ],
            "description": "ENS name for the address, when known"
          },
          "score": {
            "type": "number",
            "description": "Signed reputation score from -100 to +100. Lower is worse."
          },
          "bandCode": {
            "type": "string",
            "description": "Band identifier, e.g. LOW_RISK"
          },
          "band": {
            "type": "string",
            "description": "Reputation band, e.g. Low Risk"
          },
          "confidence": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "High",
                  "Medium",
                  "Low"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Engine confidence for this run"
          },
          "sanctioned": {
            "type": "boolean",
            "description": "True if the address is a direct OFAC match"
          },
          "transactionCount": {
            "type": "integer",
            "description": "Number of transactions analysed"
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "factor": {
                  "type": "string"
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "High",
                    "Medium",
                    "Low"
                  ]
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "factor",
                "severity",
                "message"
              ],
              "additionalProperties": false
            },
            "description": "Up to 10 signals behind this run, most severe first"
          },
          "screenedAt": {
            "type": "string",
            "description": "When the screen ran (ISO-8601)"
          },
          "reportUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Link to the full report on the Probity dashboard"
          }
        },
        "required": [
          "screeningId",
          "address",
          "ensName",
          "score",
          "bandCode",
          "band",
          "confidence",
          "sanctioned",
          "transactionCount",
          "evidence",
          "screenedAt",
          "reportUrl"
        ],
        "additionalProperties": false
      },
      "description": "Recent screening runs, newest first, each with the same detail as screen_address"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the authenticated user's monitoring events: material reputation changes detected on their monitored addresses, oldest first, each with the change type, a summary, and the band transition. Also returns a deterministic digest that rolls up the window into one sentence. Page forward by passing the returned nextCursor as cursor. Bound the window with since and until, or restrict to one address with address. Costs zero credits.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "ISO-8601 lower bound. Only events at or after this time are returned."
    },
    "until": {
      "type": "string",
      "description": "ISO-8601 upper bound. Only events at or before this time are returned."
    },
    "cursor": {
      "type": "string",
      "description": "Pass the nextCursor from a prior call to page forward."
    },
    "address": {
      "type": "string",
      "description": "Restrict to one monitored address (0x...). Omit for the whole portfolio."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Number of events (1-100, default 20)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Event id. Pass it as cursor to page past this event."
          },
          "address": {
            "type": "string",
            "description": "The monitored address"
          },
          "detectedAt": {
            "type": "string",
            "description": "When the change was detected (ISO-8601)"
          },
          "triggerType": {
            "type": "string",
            "description": "Primary change type: floor_added, band_downgrade, band_upgrade, or score_delta"
          },
          "direction": {
            "type": "string",
            "description": "downgrade or upgrade"
          },
          "minor": {
            "type": "boolean",
            "description": "True for a trivial change safe to de-emphasise"
          },
          "summary": {
            "type": "string",
            "description": "Summary of the change"
          },
          "bandFrom": {
            "type": "string",
            "description": "Reputation band before the change"
          },
          "bandTo": {
            "type": "string",
            "description": "Reputation band after the change"
          }
        },
        "required": [
          "id",
          "address",
          "detectedAt",
          "triggerType",
          "direction",
          "minor",
          "summary",
          "bandFrom",
          "bandTo"
        ],
        "additionalProperties": false
      },
      "description": "Monitoring events in the window, oldest first"
    },
    "digest": {
      "type": "string",
      "description": "Deterministic rollup of the events in this window"
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cursor for the next page, or null when none remain"
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when more events remain past this page"
    }
  },
  "required": [
    "events",
    "digest",
    "nextCursor",
    "hasMore"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the authenticated user's current credit balance as a whole number of credits. One credit screens one address: screen_address costs 1 credit, while this call and the history, narrative, and compare tools cost zero. Check it before screen_address to confirm a screen can be afforded.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}