/api/drd/list/set

GET

Adds coins to (or updates them on) the caller's private white/black lists in the DRD. Whitelisted senders always reach your QMail inbox — they bypass the inbox fee and class rejection. Blacklisted senders are permanently rejected (Tell status 236). Lists are private: only the owner's coin can write or read them.

http://localhost:8080/api/drd/list/set?sn=9840&entries=0:11111:white,1:22222:black

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.
entries string No* Comma-separated entries, each denomination:sn:type where type is white / black (or 0 / 1). Max 200 per request. *Either entries or the single-entry parameters below.
listed_denomination integer No* Single-entry form: denomination of the coin to list.
listed_sn integer No* Single-entry form: serial number of the coin to list.
list_type string No* Single-entry form: white or black.

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-set",
    "success": true,
    "entries_sent": 2,
    "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

400 Bad Request

Malformed entry, unknown list type, or more than 200 entries.

{
    "error": true,
    "message": "Invalid entries item: invalid type (must be white or black)",
    "code": 400
}

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 accepted the list update",
    "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/set?sn=9840&entries=0:11111:white,1:22222:black"

JavaScript Example

// Whitelist a friend, blacklist a spammer, in one call
const entries = '0:11111:white,1:22222:black';

fetch(`http://localhost:8080/api/drd/list/set?sn=9840&entries=${entries}`)
    .then(r => r.json())
    .then(data => console.log(data.success
        ? `${data.entries_sent} entries set on ${data.pass_count}/25 servers`
        : `Error: ${data.message}`));

Python Example

import requests

url = 'http://localhost:8080/api/drd/list/set'
params = {'sn': 9840, 'entries': '0:11111:white,1:22222:black'}
data = requests.get(url, params=params).json()
print(f"Set {data.get('entries_sent')} entries" if data.get('success')
      else f"Error: {data.get('message')}")

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.
  • Setting an entry that already exists updates its type — moving a sender from white to black takes one call.
  • Whitelist beats everything: a whitelisted sender pays no inbox fee and bypasses class rejection. Blacklist rejects the sender's Tells with permanent status 236.
  • A batch is validated before anything is written, so one bad entry rejects the whole request rather than leaving the list half-updated.