/api/drd/user/get

GET

Fetches a single record from the Distributed Resource Directory. Open read — no authentication. Use it to look up a recipient's display name, inbox fee, class rejection and account age before sending QMail. When several servers hold different versions, the copy with the newest updated_at is returned.

http://localhost:8080/api/drd/user/get?denomination=1&sn=9840

Parameters

Name Type Required Description
denomination integer Yes Denomination code of the record's coin (-8 to 6).
sn integer Yes Serial number of the record's coin.
wallet_path string No Wallet used to pick the request-encryption coin. Defaults to the Default wallet.

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-user-get",
    "success": true,
    "user": {
        "denomination": 1,
        "serial_number": 9840,
        "inbox_fee": "0.5",
        "inbox_fee_units": 50000000,
        "first_symbol": 3,
        "second_symbol": 14,
        "class_rejection": 0,
        "created_at": 1783741315,
        "updated_at": 1783741315,
        "account_age_seconds": 86400,
        "first_name": "Alice",
        "last_name": "Example"
    },
    "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 }
    ]
}

inbox_fee is the exact decimal CC string; inbox_fee_units is the same value in 10-8 CC integer units.

Error Responses

400 Bad Request

Missing or invalid denomination / sn.

{
    "error": true,
    "message": "Missing required parameters: denomination, sn",
    "code": 400
}

404 Not Found

The coin has no directory record (RAIDA status 193 — a definite answer, not a network problem).

{
    "error": true,
    "message": "User not registered in DRD",
    "code": 404,
    "denomination": 1,
    "serial_number": 9840
}

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 record",
    "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/user/get?denomination=1&sn=9840"

JavaScript Example

fetch(`http://localhost:8080/api/drd/user/get?denomination=1&sn=9840`)
    .then(r => r.json())
    .then(data => {
        if (data.success) {
            const u = data.user;
            const days = Math.floor(u.account_age_seconds / 86400);
            console.log(`${u.first_name} ${u.last_name} — inbox fee ${u.inbox_fee} CC, account ${days} days old`);
        } else if (data.code === 404) {
            console.log('Not registered — sending QMail will cost the default fee');
        }
    });

Python Example

import requests

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

if data.get('success'):
    u = data['user']
    print(f"{u['first_name']} {u['last_name']}: fee {u['inbox_fee']} CC, "
          f"age {u['account_age_seconds'] // 86400} days")
elif data.get('code') == 404:
    print('Recipient not registered in DRD')

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.
  • account_age_seconds derives from created_at, the anti-scam signal: it survives updates and only resets on delete + repost. Surface it in the UI.
  • Recipients with NO directory record cost the sender the network default Tell fee (10 CC) — warn users before they message unregistered addresses.
  • 404 means "not registered", a definite answer from the servers; 502 means no server could be reached or all rejected the request.