# External Endpoints

These handlers are deployed under the public API surface. They either expose market intelligence sourced from Horizon or broker read-only access to the `PII` table for authorized operators.

## `external/federation`
- **Route**: `GET /federation?q={value}&type={NAME|PLUS|ID}`
- **Purpose**: Resolve BlockTransfer federation addresses into Stellar public keys (and optionally residency metadata).
- **Auth**: None. Response varies by `type`:
  - `NAME`: Requires `{investorAccount}*BLOCKTRANSFER.COM`; returns `stellar_address` and resolved `account_id`.
  - `PLUS`: Accepts an internal account string; returns `PK` and the account's home country.
  - `ID`: Not implemented; responds with HTTP 501.
- **Failure modes**: 400 for malformed input, 404 when the account is missing, 500 on DynamoDB/Horizon errors.

## `external/getAssetInfo`
- **Route**: `GET /assets/{code}` where `{code}` is either an asset code or numeric CIK.
- **Purpose**: If `{code}` is alpha-numeric, summarizes outstanding supply for the issuer's asset by summing unrestricted balances, claimable balances, and liquidity pools. If numeric, enumerates all asset codes assigned to that CIK using `stellar.toml`.
- **Dependencies**: Horizon assets endpoint and `https://blocktransfer.com/.well-known/stellar.toml`.
- **Failure modes**: 404 when the asset or issuer cannot be resolved.

## `external/getNumOutstanding`
- **Route**: `GET /assets/{code}/outstanding`
- **Purpose**: Lightweight variant that returns the total outstanding supply as a string. Shares the same Horizon aggregation logic as `getAssetInfo` but omits TOML lookups.
- **Notes**: Returns `0` if the asset cannot be found on Horizon.

## `external/getLedgerBalances`
- **Route**: `GET /assets/{code}/balances`
- **Purpose**: Walks Horizon account and claimable balance collections, returning a JSON map keyed by account ID with `unrestricted` and optional `restricted` balances.
- **Pagination**: Iteratively follows Horizon's `_links.next` URL until all pages have been loaded.
- **Extension points**: Placeholder for adding Soroban contract-held totals once those ledgers go live.

## `external/getPII`
- **Route**: `GET /pii/{PK}`
- **Auth**: API Gateway `AWS_IAM` (the Lambda expects IAM-signed requests).
- **Purpose**: Fetches a single investor profile from the `PII` table by primary key. Returns the DynamoDB item on success; emits `404` when absent.

## `external/getBatchPII`
- **Route**: `GET /pii?PKs=PK1,PK2,...`
- **Auth**: API Gateway `AWS_IAM`.
- **Purpose**: Batch-fetch up to 100 records from `PII` using DynamoDB's `BatchGetItem`.
- **Behavior**: Responds with the raw DynamoDB items when all keys are present; returns `404` listing the missing PKs; raises `400` if the query string is absent; bubbles `500` for other failures.