djd-agent-score

TypeScript client SDK for the DJD Agent Score API focused on screening wallets before payouts or paid x402 work.

Install

npm install djd-agent-score

Quick Start

import { DJDAgentScore } from 'djd-agent-score'

const client = new DJDAgentScore()

// Free: basic score (10/day)
const basic = await client.getBasicScore('0x1234...')
console.log(basic.score, basic.tier) // 72 "Established"

// Optional: broader context once screening is in place
const history = await client.getScoreHistory('0x1234...')

// Optional: ecosystem metrics for additional context
const economy = await client.getEconomyMetrics('daily', 7)

Paid Endpoints (API key)

Monthly-plan access uses a normal Bearer API key:

const client = new DJDAgentScore({
  apiKey: 'djd_live_...',
})

const full = await client.getFullScore('0x1234...')
const history = await client.getScoreHistory('0x1234...', { limit: 25 })

If you pass both apiKey and paymentHeaderProvider, the SDK uses the API key and skips x402 payment headers.

Paid Endpoints (x402)

Paid endpoints require a payment header provider that generates x402 USDC payment headers:

const client = new DJDAgentScore({
  paymentHeaderProvider: async (endpoint, price) => {
    // Your x402 payment logic here
    return base64EncodedPaymentHeader
  },
})

// $0.10 USDC --- full score with dimensions
const full = await client.getFullScore('0x1234...')

// $0.15 USDC --- score history with trend analysis
const history = await client.getScoreHistory('0x1234...', { limit: 25 })

// $0.25 USDC --- force recalculation
const fresh = await client.refreshScore('0x1234...')

// $0.02 USDC --- submit fraud report
await client.submitReport({
  target: '0xbad...',
  reporter: '0xgood...',
  reason: 'payment_fraud',
  details: 'Failed to deliver on x402 payment',
})

API Reference

| Method | Endpoint | Price | Description | |--------|----------|-------|-------------| | getBasicScore(wallet) | GET /v1/score/basic | Free (10/day) | Basic score + tier | | getFullScore(wallet) | GET /v1/score/full | $0.10 | Full score + dimensions | | refreshScore(wallet) | GET /v1/score/refresh | $0.25 | Force recalculation | | getScoreHistory(wallet) | GET /v1/score/history | $0.15 | Historical trend | | submitReport(body) | POST /v1/report | $0.02 | Report fraud | | getEconomyMetrics(period, limit) | GET /v1/data/economy | Free | Ecosystem context | | registerAgent(body) | POST /v1/agent/register | Free | Optional identity profile | | submitCompute(wallet) | POST /v1/score/compute | --- | Async compute | | pollJob(jobId) | GET /v1/score/job/:id | --- | Check job status | | waitForScore(wallet) | --- | --- | Poll until complete |

The client is most useful when you start with getBasicScore() for screening and only layer in history or forensics when the workflow needs more depth.

Error Handling

import { DJDScoreError } from 'djd-agent-score'

try {
  await client.getBasicScore('invalid')
} catch (err) {
  if (err instanceof DJDScoreError) {
    console.log(err.status) // 400
    console.log(err.body)   // { error: 'Invalid wallet address' }
  }
}

Configuration

const client = new DJDAgentScore({
  apiKey: 'djd_live_...', // Optional Bearer API key for monthly-plan access
  baseUrl: 'https://djdagentscore.dev',
  timeoutMs: 15_000,      // Request timeout (default: 30s)
  maxRetries: 3,           // Retry on 5xx (default: 2)
  paymentHeaderProvider,   // Optional x402 payment header generator
  fetch: customFetch,      // Custom fetch implementation
})

License

MIT