===============
LIBRARY RULES
===============
From library maintainers:
- Use the live x402 catalog as source of truth: https://api.ledgercore.io/api/v1/x402/catalog
- Use x402 v2 payment flow.
- Payment challenge is returned with PAYMENT-REQUIRED.
- Payment retry uses PAYMENT-SIGNATURE.
- Payment token is USDC on Base mainnet.
- No LedgerBrain API key is required for x402 endpoints.
- Use KYA for address risk, KYT for transaction risk, and KYE for entity due diligence.
- KYT request uses txid, not tx_hash.
- KYE request uses name, not entity.
- KYA, KYT, and KYE are all live paid endpoints confirmed in the catalog.
- Do not treat LedgerBrain reports as legal advice.
- Compliance risk screening includes AML/sanctions-related risk context where available in the report.

### GET /api/v1/portals/x402

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Human-readable x402 API portal.

```APIDOC
## GET https://api.ledgercore.io/api/v1/portals/x402

### Description
Human-readable x402 API portal.

### Method
GET

### Endpoint
https://api.ledgercore.io/api/v1/portals/x402
```

--------------------------------

### Agent Policy Example

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/agent-integration-guide.md

This text outlines a sample agent policy for handling crypto payments, including pre-transfer checks (KYA), post-receipt analysis (KYT), and counterparty context gathering (KYE).

```text
If I am about to send funds to a crypto address:
  1. Call KYA first.
  2. If risk level is HIGH or CRITICAL, or the result requires review:
     stop and ask the operator for instructions.
  3. Otherwise, continue with payment.

If I received a crypto payment:
  1. Call KYT on the transaction (using txid, not tx_hash).
  2. If risk level is HIGH or CRITICAL, or suspicious exposure is present:
     hold fulfillment and request review.
  3. Otherwise, proceed.

If I need counterparty context:
  1. Call KYE with the entity name (using name, not entity).
  2. Use the entity intelligence report as one signal in my policy engine.
```

--------------------------------

### GET /.well-known/x402

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

x402 discovery document for agents and indexers.

```APIDOC
## GET https://api.ledgercore.io/.well-known/x402

### Description
x402 discovery document for agents and indexers.

### Method
GET

### Endpoint
https://api.ledgercore.io/.well-known/x402
```

--------------------------------

### GET /openapi.json

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

OpenAPI specification for the API.

```APIDOC
## GET https://api.ledgercore.io/openapi.json

### Description
Provides the OpenAPI specification for the API.

### Method
GET

### Endpoint
https://api.ledgercore.io/openapi.json
```

--------------------------------

### GET /api/v1/x402/catalog

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Retrieves the x402 catalog, which includes payable resources, schemas, and pricing information.

```APIDOC
## GET https://api.ledgercore.io/api/v1/x402/catalog

### Description
Provides access to the x402 catalog, detailing payable resources, schemas, and pricing.

### Method
GET

### Endpoint
https://api.ledgercore.io/api/v1/x402/catalog
```

--------------------------------

### GET /api/v1/x402/health

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Checks the health status of the x402 service.

```APIDOC
## GET https://api.ledgercore.io/api/v1/x402/health

### Description
Service health check endpoint.

### Method
GET

### Endpoint
https://api.ledgercore.io/api/v1/x402/health
```

--------------------------------

### KYA — Address Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Use the KYA endpoint before sending funds to a receiving address to get an address risk report. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

```APIDOC
## KYA — Address Risk Report

### Description
Use the KYA endpoint before sending funds to a receiving address to get an address risk report. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kya/report

### Parameters
#### Request Body
- **address** (string) - Required - The address to report on.
- **chain** (string) - Required - The blockchain network of the address (e.g., `bitcoin`, `ethereum`).

### Request Example
```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kya/report \
  -H 'Content-Type: application/json' \
  -d '{ \
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna", \
    "chain": "bitcoin" \
  }'
```

### Response
#### Success Response (200)
(Response structure not detailed in source, but would contain risk assessment)

#### Error Response (402)
```text
HTTP/2 402 Payment Required
PAYMENT-REQUIRED: <challenge with payTo, price, network, token>
```

#### Retrying After Payment
```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kya/report \
  -H 'Content-Type: application/json' \
  -H 'PAYMENT-SIGNATURE: <your-signed-payment-proof>' \
  -d '{ \
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna", \
    "chain": "bitcoin" \
  }'
```
```

--------------------------------

### KYE — Entity Intelligence Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Use the KYE endpoint for counterparty or entity due diligence context to get an entity intelligence report. Note that the request field is `name`, not `entity`. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

```APIDOC
## KYE — Entity Intelligence Report

### Description
Use the KYE endpoint for counterparty or entity due diligence context to get an entity intelligence report. Note that the request field is `name`, not `entity`. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kye/report

### Parameters
#### Request Body
- **name** (string) - Required - The name of the entity to report on.

### Request Example
```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kye/report \
  -H 'Content-Type: application/json' \
  -d '{ \
    "name": "Binance" \
  }'
```

### Response
#### Success Response (200)
(Response structure not detailed in source, but would contain entity intelligence)

#### Error Response (402)
```text
HTTP/2 402 Payment Required
PAYMENT-REQUIRED: <challenge with payTo, price, network, token>
```

#### Retrying After Payment
(Retry request is the same as the initial request, but with the `PAYMENT-SIGNATURE` header added.)
```

--------------------------------

### KYT — Transaction Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Use the KYT endpoint after receiving a payment or when reviewing a transaction to get a transaction risk report. Note that the request field is `txid`, not `tx_hash`. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

```APIDOC
## KYT — Transaction Risk Report

### Description
Use the KYT endpoint after receiving a payment or when reviewing a transaction to get a transaction risk report. Note that the request field is `txid`, not `tx_hash`. Paid endpoints return `HTTP 402 Payment Required` on the first unauthenticated request. After completing the x402 payment, retry with the `PAYMENT-SIGNATURE` header.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kyt/report

### Parameters
#### Request Body
- **txid** (string) - Required - The transaction ID to report on.
- **chain** (string) - Required - The blockchain network of the transaction (e.g., `bitcoin`, `ethereum`).

### Request Example
```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kyt/report \
  -H 'Content-Type: application/json' \
  -d '{ \
    "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b", \
    "chain": "bitcoin" \
  }'
```

### Response
#### Success Response (200)
(Response structure not detailed in source, but would contain risk assessment)

#### Error Response (402)
```text
HTTP/2 402 Payment Required
PAYMENT-REQUIRED: <challenge with payTo, price, network, token>
```

#### Retrying After Payment
(Retry request is the same as the initial request, but with the `PAYMENT-SIGNATURE` header added.)
```

--------------------------------

### Discover Payable Resources

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

These endpoints are free and do not require payment. They allow you to discover the x402 discovery document, the full catalog with resource schemas and pricing, OpenAPI specification information, and perform a health check.

```APIDOC
## Discover Payable Resources

### Description
These endpoints are free and do not require payment. They allow you to discover the x402 discovery document, the full catalog with resource schemas and pricing, OpenAPI specification information, and perform a health check.

### Endpoints

- **x402 discovery document**
  ```bash
  curl -sS https://api.ledgercore.io/.well-known/x402 | jq
  ```

- **Full catalog with resource schemas and pricing**
  ```bash
  curl -sS https://api.ledgercore.io/api/v1/x402/catalog | jq
  ```

- **OpenAPI spec info**
  ```bash
  curl -sS https://api.ledgercore.io/openapi.json | jq '.info'
  ```

- **Health check**
  ```bash
  curl -sS https://api.ledgercore.io/api/v1/x402/health | jq
  ```
```

--------------------------------

### Discover x402 Discovery Document

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Fetches the x402 discovery document to understand available resources. This is a free, unauthenticated request.

```bash
curl -sS https://api.ledgercore.io/.well-known/x402 | jq
```

--------------------------------

### Discover Full Catalog

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Retrieves the full API catalog, including resource schemas and pricing. This is a free, unauthenticated request.

```bash
curl -sS https://api.ledgercore.io/api/v1/x402/catalog | jq
```

--------------------------------

### Discover x402 API Catalog

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/javascript-fetch.md

Fetches the available x402 API resources from the catalog. Use this to understand available services and their pricing.

```javascript
const API = 'https://api.ledgercore.io';

async function discoverCatalog() {
  const res = await fetch(`${API}/api/v1/x402/catalog`);
  if (!res.ok) throw new Error(`Catalog fetch failed: ${res.status}`);
  const { data } = await res.json();
  // data.resources contains kya_report, kyt_report, kye_report with schemas and pricing
  return data;
}
```

--------------------------------

### Run KYE Entity Due Diligence Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/javascript-fetch.md

Initiates a Know Your Entity (KYE) intelligence report for a specified counterparty name. This function uses an x402-capable fetch wrapper to query the entity report.

```javascript
/**
 * Run a KYE entity intelligence report for a named counterparty.
 * Note: the request field is name, not entity.
 *
 * @param {Function} x402Fetch - x402-capable fetch function
 * @param {string} entityName - entity name to look up, e.g. "Binance"
 * @returns {object} report
 */
async function runKyeEntityCheck(x402Fetch, entityName) {
  const response = await x402Fetch(`${API}/api/v1/x402/kye/report`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: entityName }), // use name, not entity
    maxSpend: '1.00',
  });

  if (!response.ok) {
    throw new Error(`LedgerBrain KYE failed: ${response.status}`);
  }

  return response.json();
}
```

--------------------------------

### Discover OpenAPI Specification Info

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Fetches information about the OpenAPI specification for the API. This is a free, unauthenticated request.

```bash
curl -sS https://api.ledgercore.io/openapi.json | jq '.info'
```

--------------------------------

### Request Entity Intelligence Report (KYE) - Initial Unauthenticated

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Initiates an entity intelligence report request. The first attempt will return a 402 Payment Required error, prompting for payment. Use 'name' for the entity identifier.

```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kye/report \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Binance"
  }'
```

--------------------------------

### Request Address Risk Report (KYA) - Initial Unauthenticated

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Initiates an address risk report request. The first attempt will return a 402 Payment Required error, prompting for payment.

```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kya/report \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
    "chain": "bitcoin"
  }'
```

--------------------------------

### x402 Catalog

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/README.md

Retrieves the catalog of payable resources and their schemas available via x402.

```APIDOC
## GET /api/v1/x402/catalog

### Description
Retrieves the catalog of payable resources and their schemas available via x402.

### Method
GET

### Endpoint
https://api.ledgercore.io/api/v1/x402/catalog

### Response
#### Success Response (200)
- **catalog** (object) - An object containing details of available reports, prices, and schemas.

#### Response Example
```json
{
  "catalog": {
    "kya_report": {
      "price": "1.00 USDC",
      "schema": {
        "address": "string",
        "chain": "string"
      }
    },
    "kyt_report": {
      "price": "1.00 USDC",
      "schema": {
        "txid": "string",
        "chain": "string"
      }
    }
  }
}
```
```

--------------------------------

### Request Address Risk Report (KYA) - After Payment

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Retries the address risk report request after completing the x402 payment. Requires the PAYMENT-SIGNATURE header.

```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kya/report \
  -H 'Content-Type: application/json' \
  -H 'PAYMENT-SIGNATURE: <your-signed-payment-proof>' \
  -d '{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
    "chain": "bitcoin"
  }'
```

--------------------------------

### Request Transaction Risk Report (KYT) - Initial Unauthenticated

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Initiates a transaction risk report request. The first attempt will return a 402 Payment Required error, prompting for payment. Use 'txid' for the transaction identifier.

```bash
curl -i -X POST https://api.ledgercore.io/api/v1/x402/kyt/report \
  -H 'Content-Type: application/json' \
  -d '{
    "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
    "chain": "bitcoin"
  }'
```

--------------------------------

### POST /api/v1/x402/kye/report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Generates an entity intelligence report (KYE) for due diligence and counterparty intelligence.

```APIDOC
## POST https://api.ledgercore.io/api/v1/x402/kye/report

### Description
Generates an entity intelligence report (KYE) for entity due diligence and counterparty intelligence.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kye/report

### Parameters
#### Request Body
- **name** (string) - Yes - Entity name (min 2 chars, e.g. "Binance", "Luno")

### Request Example
```json
{
  "name": "Binance"
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Run KYT Transaction Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/javascript-fetch.md

Executes a Know Your Transaction (KYT) risk assessment on a received payment's transaction ID. Requires an x402-capable fetch function and specifies the chain and transaction ID.

```javascript
/**
 * Run a KYT transaction risk report after receiving a payment.
 * Note: the request field is txid, not tx_hash.
 *
 * @param {Function} x402Fetch - x402-capable fetch function
 * @param {string} chain - e.g. "bitcoin"
 * @param {string} txid - transaction ID (64 hex chars)
 * @returns {{ decision: string, report: object }}
 */
async function runKytAfterReceivingPayment(x402Fetch, chain, txid) {
  const response = await x402Fetch(`${API}/api/v1/x402/kyt/report`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ txid, chain }), // use txid, not tx_hash
    maxSpend: '1.00',
  });

  if (!response.ok) {
    throw new Error(`LedgerBrain KYT failed: ${response.status}`);
  }

  const report = await response.json();

  if (
    report?.data?.risk_level === 'HIGH' ||
    report?.data?.risk_level === 'CRITICAL'
  ) {
    return { decision: 'hold_for_review', report };
  }

  return { decision: 'proceed', report };
}
```

--------------------------------

### KYE Entity Context Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/agent-integration-guide.md

Obtain context about a counterparty, exchange, service, wallet cluster, or entity by running KYE. Use `name` as the request field for entity identification.

```APIDOC
## POST /api/v1/x402/kye/report

### Description
Retrieves contextual intelligence for a given entity.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kye/report

### Parameters
#### Request Body
- **name** (string) - Required - The name of the entity (e.g., exchange, service, wallet cluster).

### Request Example
{
  "name": "Binance"
}

### Response
#### Success Response (200)
- **entity_type** (string) - The type of entity (e.g., EXCHANGE, SERVICE, WALLET).
- **risk_profile** (object) - The risk profile of the entity.
- **compliance_status** (string) - The compliance status of the entity.
- **intelligence_summary** (string) - A summary of intelligence about the entity.

#### Response Example
{
  "entity_type": "EXCHANGE",
  "risk_profile": {
    "overall_risk": "MEDIUM",
    "regulatory_compliance": "GOOD",
    "sanctions_exposure": "LOW"
  },
  "compliance_status": "COMPLIANT",
  "intelligence_summary": "Binance is a major global cryptocurrency exchange with robust compliance measures."
}
```

--------------------------------

### KYT Transaction Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/agent-integration-guide.md

After receiving a crypto payment or reviewing an on-chain transfer, run KYT to assess transaction risk. Note that `txid` should be used instead of `tx_hash`.

```APIDOC
## POST /api/v1/x402/kyt/report

### Description
Retrieves a risk report for a given cryptocurrency transaction.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kyt/report

### Parameters
#### Request Body
- **txid** (string) - Required - The transaction ID of the cryptocurrency transfer.
- **chain** (string) - Required - The blockchain network (e.g., "bitcoin").

### Request Example
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "chain": "bitcoin"
}

### Response
#### Success Response (200)
- **risk_score** (number) - The calculated risk score for the transaction.
- **risk_level** (string) - The assessed risk level (e.g., LOW, MEDIUM, HIGH, CRITICAL).
- **exposure_context** (object) - Contextual information about the transaction's exposure.

#### Response Example
{
  "risk_score": 70,
  "risk_level": "MEDIUM",
  "exposure_context": {
    "source_address_risk": "HIGH",
    "destination_address_risk": "MEDIUM",
    "transfer_pattern": "unusual"
  }
}
```

--------------------------------

### POST /api/v1/x402/kya/report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Generates an address risk report (KYA) to screen addresses for compliance risk before sending funds.

```APIDOC
## POST https://api.ledgercore.io/api/v1/x402/kya/report

### Description
Generates an address risk report (KYA) for screening addresses for compliance risk, typically before sending funds.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kya/report

### Parameters
#### Request Body
- **address** (string) - Yes - Blockchain address to analyze
- **chain** (string) - Yes - Blockchain network (see supported chains below)
- **asset** (string) - No - ERC-20 contract address (ethereum only)
- **reference_id** (string) - No - Optional client reference ID

### Request Example
```json
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
  "chain": "bitcoin"
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### POST /api/v1/x402/kyt/report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Generates a transaction risk report (KYT) to assess compliance risk for incoming crypto payments or reviewed transactions.

```APIDOC
## POST https://api.ledgercore.io/api/v1/x402/kyt/report

### Description
Generates a transaction risk report (KYT) to provide compliance risk context for crypto payments or transactions.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kyt/report

### Parameters
#### Request Body
- **txid** (string) - Yes - Transaction ID (64 hex chars; 0x prefix optional for ETH)
- **chain** (string) - Yes - Blockchain network (see supported chains below)
- **asset** (string) - No - ERC-20 contract address (ethereum only)
- **timeout** (integer) - No - Request timeout in ms (default 300000, min 1000, max 900000)
- **reference_id** (string) - No - Optional client reference ID

### Request Example
```json
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "chain": "bitcoin"
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### KYA Address Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/agent-integration-guide.md

Run a KYA address risk report on a receiving address before sending crypto. This helps in reviewing the returned risk score, level, labels, and exposure context to ensure compliance with agent owner policies.

```APIDOC
## POST /api/v1/x402/kya/report

### Description
Retrieves a risk report for a given cryptocurrency address.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kya/report

### Parameters
#### Request Body
- **address** (string) - Required - The cryptocurrency address to report on.
- **chain** (string) - Required - The blockchain network (e.g., "bitcoin").

### Request Example
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
  "chain": "bitcoin"
}

### Response
#### Success Response (200)
- **risk_score** (number) - The calculated risk score for the address.
- **risk_level** (string) - The assessed risk level (e.g., LOW, MEDIUM, HIGH, CRITICAL).
- **labels** (array) - A list of labels associated with the address.
- **exposure_context** (object) - Contextual information about the address's exposure.

#### Response Example
{
  "risk_score": 85,
  "risk_level": "MEDIUM",
  "labels": ["exchange", "high_volume"],
  "exposure_context": {
    "recent_activity": "high",
    "associated_entities": ["Binance", "Coinbase"]
  }
}
```

--------------------------------

### Run KYA Address Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/javascript-fetch.md

Performs a Know Your Address (KYA) risk assessment on a given blockchain address before sending funds. Requires an x402-capable fetch function and sets a maxSpend guard.

```javascript
/**
 * Run a KYA address risk report before sending funds.
 * x402Fetch must be an x402-capable fetch wrapper that handles
 * the PAYMENT-REQUIRED challenge and PAYMENT-SIGNATURE retry automatically.
 *
 * @param {Function} x402Fetch - x402-capable fetch function from your wallet/SDK
 * @param {string} chain - e.g. "bitcoin", "ethereum"
 * @param {string} address - receiving address to screen
 * @returns {{ decision: string, report: object }}
 */
async function runKyaBeforeSendingFunds(x402Fetch, chain, address) {
  const response = await x402Fetch(`${API}/api/v1/x402/kya/report`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ address, chain }),
    maxSpend: '1.00', // USDC — guard against unexpected price changes
  });

  if (!response.ok) {
    throw new Error(`LedgerBrain KYA failed: ${response.status}`);
  }

  const report = await response.json();

  // Example policy. Tune risk_level thresholds to your own policy.
  if (
    report?.data?.risk_level === 'HIGH' ||
    report?.data?.risk_level === 'CRITICAL'
  ) {
    return { decision: 'pause_for_review', report };
  }

  return { decision: 'continue', report };
}
```

--------------------------------

### KYE Entity Intelligence Report Request Schema

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Schema for requesting an entity intelligence report. Use this for entity due diligence and counterparty intelligence.

```json
{
  "name": "Binance"
}
```

--------------------------------

### KYA Address Risk Report Request Schema

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Schema for requesting an address risk report. Use this before sending funds or for compliance screening.

```json
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
  "chain": "bitcoin"
}
```

--------------------------------

### KYA Address Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/README.md

Generates a risk report for a given cryptocurrency address. This is useful for screening wallets before sending funds.

```APIDOC
## POST /api/v1/x402/kya/report

### Description
Generates a risk report for a given cryptocurrency address. This is useful for screening wallets before sending funds.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kya/report

### Parameters
#### Request Body
- **address** (string) - Required - The cryptocurrency address to screen.
- **chain** (string) - Required - The blockchain network of the address (e.g., bitcoin, ethereum).
- **asset** (string) - Optional - For Ethereum, the ERC-20 contract address.
- **reference_id** (string) - Optional - A custom identifier for the request.

### Request Example
```json
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
  "chain": "bitcoin"
}
```

### Response
#### Success Response (200)
- **risk_score** (number) - The calculated risk score for the address.
- **flags** (array) - A list of risk flags associated with the address.
- **entity** (object) - Information about any identified entity associated with the address.

#### Response Example
```json
{
  "risk_score": 75,
  "flags": ["high_risk_exchange", "sanctioned_address"],
  "entity": {
    "name": "Known Risky Exchange",
    "type": "exchange"
  }
}
```
```

--------------------------------

### KYT Transaction Risk Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/README.md

Analyzes a cryptocurrency transaction to assess its risk level. Use this after receiving a payment to review its compliance.

```APIDOC
## POST /api/v1/x402/kyt/report

### Description
Analyzes a cryptocurrency transaction to assess its risk level. Use this after receiving a payment to review its compliance.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kyt/report

### Parameters
#### Request Body
- **txid** (string) - Required - The transaction ID (txid) of the transaction to screen.
- **chain** (string) - Required - The blockchain network of the transaction.
- **asset** (string) - Optional - For Ethereum, the ERC-20 contract address.
- **timeout** (integer) - Optional - Timeout in seconds for the transaction analysis.
- **reference_id** (string) - Optional - A custom identifier for the request.

### Request Example
```json
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "chain": "bitcoin"
}
```

### Response
#### Success Response (200)
- **risk_score** (number) - The calculated risk score for the transaction.
- **flags** (array) - A list of risk flags associated with the transaction.
- **involved_addresses** (array) - A list of addresses involved in the transaction.

#### Response Example
```json
{
  "risk_score": 80,
  "flags": ["mixers_involved", "unauthorized_entity"],
  "involved_addresses": [
    "bc1q...",
    "1A1z..."
  ]
}
```
```

--------------------------------

### KYE Entity Intelligence Report

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/README.md

Provides due diligence context for a given entity. Useful for counterparty or exchange verification.

```APIDOC
## POST /api/v1/x402/kye/report

### Description
Provides due diligence context for a given entity. Useful for counterparty or exchange verification.

### Method
POST

### Endpoint
https://api.ledgercore.io/api/v1/x402/kye/report

### Parameters
#### Request Body
- **name** (string) - Required - The name of the entity to look up (minimum 2 characters).

### Request Example
```json
{
  "name": "Binance"
}
```

### Response
#### Success Response (200)
- **entity_name** (string) - The name of the matched entity.
- **entity_type** (string) - The type of entity (e.g., exchange, service, individual).
- **risk_summary** (string) - A summary of the entity's risk profile.
- **associated_addresses** (array) - A list of known addresses associated with the entity.

#### Response Example
```json
{
  "entity_name": "Binance",
  "entity_type": "exchange",
  "risk_summary": "Major global exchange with some regulatory scrutiny.",
  "associated_addresses": [
    "0x...",
    "bc1q..."
  ]
}
```
```

--------------------------------

### KYT Transaction Risk Report Request Schema

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/docs/endpoints.md

Schema for requesting a transaction risk report. Use this when receiving payments or reviewing transactions for compliance.

```json
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "chain": "bitcoin"
}
```

--------------------------------

### Service Health Check

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/README.md

Checks the operational status of the LedgerBrain x402 API service.

```APIDOC
## GET /api/v1/x402/health

### Description
Checks the operational status of the LedgerBrain x402 API service.

### Method
GET

### Endpoint
https://api.ledgercore.io/api/v1/x402/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Check API Health

Source: https://github.com/silversixpence-crypto/ledgerbrain-x402-agent-docs/blob/main/examples/curl.md

Performs a health check on the API. This is a free, unauthenticated request.

```bash
curl -sS https://api.ledgercore.io/api/v1/x402/health | jq
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.