curl --request POST \
--url https://app.blockgence.com/v1/cases/{token}/annotations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"chain": "<string>",
"address": "<string>",
"role": "<string>",
"source": {
"analysis": "<string>",
"subject": "<string>"
},
"evidence": [
{
"kind": "<string>",
"tx": "<string>"
}
],
"offramp_candidate": false,
"label": "<string>",
"summary": "<string>"
}
'import requests
url = "https://app.blockgence.com/v1/cases/{token}/annotations"
payload = {
"chain": "<string>",
"address": "<string>",
"role": "<string>",
"source": {
"analysis": "<string>",
"subject": "<string>"
},
"evidence": [
{
"kind": "<string>",
"tx": "<string>"
}
],
"offramp_candidate": False,
"label": "<string>",
"summary": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chain: '<string>',
address: '<string>',
role: '<string>',
source: {analysis: '<string>', subject: '<string>'},
evidence: [{kind: '<string>', tx: '<string>'}],
offramp_candidate: false,
label: '<string>',
summary: '<string>'
})
};
fetch('https://app.blockgence.com/v1/cases/{token}/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.blockgence.com/v1/cases/{token}/annotations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chain' => '<string>',
'address' => '<string>',
'role' => '<string>',
'source' => [
'analysis' => '<string>',
'subject' => '<string>'
],
'evidence' => [
[
'kind' => '<string>',
'tx' => '<string>'
]
],
'offramp_candidate' => false,
'label' => '<string>',
'summary' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.blockgence.com/v1/cases/{token}/annotations"
payload := strings.NewReader("{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.blockgence.com/v1/cases/{token}/annotations")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/cases/{token}/annotations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"detail": "<string>",
"error": "<string>"
}{
"detail": "<string>",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>",
"error": "<string>"
}Add an annotation to a case
Adds to the case a victim with evidence or a destination of the funds, obtained from
GET /v1/scam/{chain}/{addr}/victims. It does not change the case graph: annotating does not trace or expand.
The body is {chain, address, role, source, evidence?, offramp_candidate?, label?, summary?}:
role:victimordestination;source:{analysis, subject}, withanalysisequal toscam_victimsandsubjectthe analyzed address;evidence: only for a victim, and mandatory. Eachevidence[].kindmust besignature_drain,approval_drain,account_executed,third_party_unresolvedorcase_loss_tx, andtxis the transaction hash ornull. Up to 25 items;offramp_candidate: only for a destination;labelandsummary: optional, up to 160 and 400 characters.
address and source.subject must be EVM addresses on a supported network; otherwise the response is 400. A
victim without victim evidence (for example, a pattern indicator or an unqualified counterparty) returns 400,
as does a destination with evidence. The server validates the shape of the evidence but does not rerun the
analysis: the victim status is supported by the cited evidence, not by the annotation.
The server fills in added_at, updated_at, added_by, via and source.recorded_seq, the latest query of
that analysis recorded in the case (or null). Adding the same address again, with the same role and the same
analysis, updates the annotation and keeps its added_at. The limit is 500 annotations per case.
The response is {ok, token, annotation, annotations}. Edit permission is required: a case shared for viewing
receives 403 with error: "case_read_only", a read-only role or API key receives 403 with
error: "read_only", and a case the caller cannot view returns 404. The addition is recorded in the annotation
log and in the evidence package.
Cost: free.
curl --request POST \
--url https://app.blockgence.com/v1/cases/{token}/annotations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"chain": "<string>",
"address": "<string>",
"role": "<string>",
"source": {
"analysis": "<string>",
"subject": "<string>"
},
"evidence": [
{
"kind": "<string>",
"tx": "<string>"
}
],
"offramp_candidate": false,
"label": "<string>",
"summary": "<string>"
}
'import requests
url = "https://app.blockgence.com/v1/cases/{token}/annotations"
payload = {
"chain": "<string>",
"address": "<string>",
"role": "<string>",
"source": {
"analysis": "<string>",
"subject": "<string>"
},
"evidence": [
{
"kind": "<string>",
"tx": "<string>"
}
],
"offramp_candidate": False,
"label": "<string>",
"summary": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chain: '<string>',
address: '<string>',
role: '<string>',
source: {analysis: '<string>', subject: '<string>'},
evidence: [{kind: '<string>', tx: '<string>'}],
offramp_candidate: false,
label: '<string>',
summary: '<string>'
})
};
fetch('https://app.blockgence.com/v1/cases/{token}/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.blockgence.com/v1/cases/{token}/annotations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chain' => '<string>',
'address' => '<string>',
'role' => '<string>',
'source' => [
'analysis' => '<string>',
'subject' => '<string>'
],
'evidence' => [
[
'kind' => '<string>',
'tx' => '<string>'
]
],
'offramp_candidate' => false,
'label' => '<string>',
'summary' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.blockgence.com/v1/cases/{token}/annotations"
payload := strings.NewReader("{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.blockgence.com/v1/cases/{token}/annotations")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/cases/{token}/annotations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chain\": \"<string>\",\n \"address\": \"<string>\",\n \"role\": \"<string>\",\n \"source\": {\n \"analysis\": \"<string>\",\n \"subject\": \"<string>\"\n },\n \"evidence\": [\n {\n \"kind\": \"<string>\",\n \"tx\": \"<string>\"\n }\n ],\n \"offramp_candidate\": false,\n \"label\": \"<string>\",\n \"summary\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"detail": "<string>",
"error": "<string>"
}{
"detail": "<string>",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>",
"error": "<string>"
}Authorizations
Headers
Path Parameters
Body
Response
Successful response.