C4 BAD API

Developer documentation · v1

C4 BAD API

Check blockchain addresses against the C4 Blockchain Address Database.

Base URL https://bad.c4lab.in/v1

Quickstart

Send your API key as a bearer token. API requests and responses use JSON.

Lookup an address
curl https://bad.c4lab.in/v1/lookup \
  --request POST \
  --header "Authorization: Bearer c4bad_YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "addresses": [{
      "network": "ethereum",
      "address": "0x1234...abcd"
    }]
  }'

Keep API keys private. Do not put them in browser code, URLs, screenshots or source control.

Roles

readerLook up addresses and read active records
adminAdd and update address records

Endpoints

MethodPathRoleUse
POST/v1/lookupreader / adminLook up up to 50 addresses
GET/v1/addresses/{uuid}reader / adminRetrieve one record
POST/v1/addressesadminAdd a verified address
PATCH/v1/addresses/{uuid}adminUpdate an address
Lookup request
POST /v1/lookup
{
  "addresses": [{
    "network": "bitcoin",
    "address": "bc1q..."
  }]
}
Add an address
POST /v1/addresses
{
  "network": "bitcoin",
  "address": "bc1q...",
  "entity_name": "Example entity",
  "entity_type": "scam",
  "category": "investment_fraud",
  "description": "Verified by C4.",
  "status": "active"
}
Update an address
PATCH /v1/addresses/{uuid}
{
  "category": "ransomware",
  "description": "Updated information verified by C4."
}

Address fields

Required

networkaddress

Optional

entity_nameentity_typecategorydescriptionfirst_seen_atlast_seen_at

Status

activeinactive

Responses and errors

Error response
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The request is invalid.",
    "details": []
  },
  "request_id": "..."
}
200 / 201
Request succeeded
400
Invalid request
401
Missing or invalid token
403
Administrator access required
404
Resource not found
409
Request conflicts with current state
429
Rate limit exceeded
500
Internal error

Include the returned request_id when reporting an API error.