curl --request POST \
--url https://app.blockgence.com/v1/returns \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"exploit_txs": [
"<string>"
],
"chain": "ethereum",
"holders": [
[
"<string>"
]
],
"protocol_addresses": [
{
"address": "<string>",
"source": "<string>",
"role": "recovery"
}
],
"incident_block": 123,
"window_days": 30
}
'import requests
url = "https://app.blockgence.com/v1/returns"
payload = {
"exploit_txs": ["<string>"],
"chain": "ethereum",
"holders": [["<string>"]],
"protocol_addresses": [
{
"address": "<string>",
"source": "<string>",
"role": "recovery"
}
],
"incident_block": 123,
"window_days": 30
}
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({
exploit_txs: ['<string>'],
chain: 'ethereum',
holders: [['<string>']],
protocol_addresses: [{address: '<string>', source: '<string>', role: 'recovery'}],
incident_block: 123,
window_days: 30
})
};
fetch('https://app.blockgence.com/v1/returns', 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/returns",
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([
'exploit_txs' => [
'<string>'
],
'chain' => 'ethereum',
'holders' => [
[
'<string>'
]
],
'protocol_addresses' => [
[
'address' => '<string>',
'source' => '<string>',
'role' => 'recovery'
]
],
'incident_block' => 123,
'window_days' => 30
]),
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/returns"
payload := strings.NewReader("{\n \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\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/returns")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/returns")
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 \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\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>"
}{
"error": "source_unavailable",
"detail": "<string>",
"source": "<string>",
"reason": "<string>",
"retryable": true,
"chain": "<string>",
"primitive": "<string>",
"operation": "<string>",
"target": "<string>",
"http_status": 123,
"retry_after": 123,
"upstream_message": "<string>",
"source_fault": true,
"failure_cause": "<string>"
}Incident fund returns
Analyzes what was returned after an incident and classifies it as a whitehat rescue, a negotiated return, a partial return or no return, against the terms of the SEAL Safe Harbor agreement read on-chain at the exploit date or against the bounty offered in an on-chain message from the protocol. It is context: it never removes the exploit label.
Request body:
chain: EVM network of the incident (defaults toethereum);exploit_txs: transactions of the incident, from 1 to 10, on the same network. They are decoded as inGET /v1/decode/{chain}/{hash};holders: other accounts that held funds from the incident, in groups (up to 10 groups of up to 5 addresses). Each group is a unit;protocol_addresses: up to 10 protocol addresses,{address, role, source}, withroleset torecovery(receives returns) orprotocol.sourceis mandatory and is cited;incident_block: block of the reference malicious exploit, if the transactions belong to a rescue that front-ran it;window_days: days after the exploit in which returns are searched, from 1 to 180 (defaults to 30).
The units are the attacker’s group of accounts, each account the attacker paid in the transaction, each group of
holders and each intermediary that returned funds on its own (unit: "relay"). Each unit includes
received, returned (what was sent to an address on the protocol side, with its role and its source),
ratio, expected_ratio with expected_basis (safe_harbor, offered_in_message or full), class
(whitehat-rescue, negotiated-return, partial-return or no_return), kept_assets, candidates (outflows
to unconfirmed destinations, which are not returns), safe_harbor_compliant, whitehat_likelihood and
reasons. The top level includes victims, stolen_usd, safe_harbor, summary (returned_usd,
recovered_ratio, classes, verdict), not_evaluated, not_covered and degraded_sources.
An invalid hash or address, a group of more than 5 addresses or a protocol address without a source returns 400, at no charge. If no exploit transaction can be read, the response is 503 at no charge; if some fail, they are declared and the analysis continues with the rest.
Cost: 40 credits base. Some operations charge less when they reuse a saved result; never more.
curl --request POST \
--url https://app.blockgence.com/v1/returns \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"exploit_txs": [
"<string>"
],
"chain": "ethereum",
"holders": [
[
"<string>"
]
],
"protocol_addresses": [
{
"address": "<string>",
"source": "<string>",
"role": "recovery"
}
],
"incident_block": 123,
"window_days": 30
}
'import requests
url = "https://app.blockgence.com/v1/returns"
payload = {
"exploit_txs": ["<string>"],
"chain": "ethereum",
"holders": [["<string>"]],
"protocol_addresses": [
{
"address": "<string>",
"source": "<string>",
"role": "recovery"
}
],
"incident_block": 123,
"window_days": 30
}
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({
exploit_txs: ['<string>'],
chain: 'ethereum',
holders: [['<string>']],
protocol_addresses: [{address: '<string>', source: '<string>', role: 'recovery'}],
incident_block: 123,
window_days: 30
})
};
fetch('https://app.blockgence.com/v1/returns', 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/returns",
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([
'exploit_txs' => [
'<string>'
],
'chain' => 'ethereum',
'holders' => [
[
'<string>'
]
],
'protocol_addresses' => [
[
'address' => '<string>',
'source' => '<string>',
'role' => 'recovery'
]
],
'incident_block' => 123,
'window_days' => 30
]),
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/returns"
payload := strings.NewReader("{\n \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\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/returns")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/returns")
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 \"exploit_txs\": [\n \"<string>\"\n ],\n \"chain\": \"ethereum\",\n \"holders\": [\n [\n \"<string>\"\n ]\n ],\n \"protocol_addresses\": [\n {\n \"address\": \"<string>\",\n \"source\": \"<string>\",\n \"role\": \"recovery\"\n }\n ],\n \"incident_block\": 123,\n \"window_days\": 30\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>"
}{
"error": "source_unavailable",
"detail": "<string>",
"source": "<string>",
"reason": "<string>",
"retryable": true,
"chain": "<string>",
"primitive": "<string>",
"operation": "<string>",
"target": "<string>",
"http_status": 123,
"retry_after": 123,
"upstream_message": "<string>",
"source_fault": true,
"failure_cause": "<string>"
}Authorizations
Headers
Body
Response
Successful response.