/api/drd/list/get

GET

Reads the caller's white/black lists from the DRD. Lists are private: reading requires the owner coin's Authenticity Numbers, so there is no way to read someone else's lists. Entries from all responding servers are merged by (denomination, serial number).

http://localhost:8080/api/drd/list/get?sn=9840

Parameters

Name Type Required Description
sn integer No Serial number of the coin that authenticates the request. The coin is loaded from the wallet's Bank or Fracked folder. Omit to use the QMail identity coin instead.
denomination integer No Optional safety check when sn is given: must match the denomination of the coin found for that serial number (-8 to 6).
wallet_path string No Wallet holding the auth coin. Defaults to the Default wallet. Only used together with sn.

Responses

Success Response (200)

The fan-out fields are shared by every DRD endpoint: pass_count / fail_count / no_response_count total 25, quorum is true when 13 or more RAIDA servers accepted, and raida_results holds one entry per server (25 entries; truncated in the examples below). Status 250 is success; failed entries include an error string.

{
    "command": "drd-list-get",
    "success": true,
    "count": 2,
    "entries": [
        {
            "denomination": 0,
            "serial_number": 11111,
            "list_type": "white"
        },
        {
            "denomination": 1,
            "serial_number": 22222,
            "list_type": "black"
        }
    ],
    "pass_count": 25,
    "fail_count": 0,
    "no_response_count": 0,
    "quorum": true,
    "raida_results": [
        { "raida": 0, "success": true, "status": 250 },
        { "raida": 1, "success": true, "status": 250 }
    ]
}

Error Responses

404 Not Found

The auth coin was not found in the wallet.

{
    "error": true,
    "message": "Auth coin not found in wallet (Bank/Fracked)",
    "code": 404
}

502 Bad Gateway

No RAIDA server accepted the request. The body names the dominant failure status and includes the full per-server detail.

{
    "error": true,
    "message": "No RAIDA returned the list",
    "code": 502,
    "raida_status_code": 200,
    "detail": "Invalid AN",
    "pass_count": 0,
    "fail_count": 25,
    "no_response_count": 0,
    "quorum": false,
    "raida_results": [
        { "raida": 0, "success": false, "status": 200, "error": "Invalid AN" }
    ]
}

Examples

cURL Example

curl -X GET "http://localhost:8080/api/drd/list/get?sn=9840"

JavaScript Example

fetch(`http://localhost:8080/api/drd/list/get?sn=9840`)
    .then(r => r.json())
    .then(data => {
        if (data.success) {
            data.entries.forEach(e =>
                console.log(`${e.list_type}: DN${e.denomination}.${e.serial_number}`));
        }
    });

Python Example

import requests

url = 'http://localhost:8080/api/drd/list/get'
data = requests.get(url, params={'sn': 9840}).json()

for e in data.get('entries', []):
    print(f"{e['list_type']}: DN{e['denomination']}.{e['serial_number']}")

Notes

  • Requests fan out to all 25 RAIDA servers in parallel; the client owns consistency. On partial success (pass_count < 25), re-issue the same request to bring stragglers up to date.
  • This operation is AN-authenticated: the auth coin's per-RAIDA Authenticity Numbers are sent with the request, and each server verifies them against its coin database (status 200 = wrong AN, 40 = unknown coin).
  • Without an sn parameter the QMail identity coin from the Mail wallet is used, so QMail users manage their directory entry with their mail identity.
  • An empty list is a 200 with count: 0.
  • Up to 1000 entries are returned per request.
  • If servers disagree (e.g. a partial list/set), the merge keeps the first responder's type for a conflicting entry — re-issue your last list update to reconverge.