Agent

Agent

An AI agent moving money, imported from the public scan index.

On-chain agents are imported as entities on the program agents and scored with the Agent Risk Skoor (ars-v1) on the same bands. Import pulls agents, their compliance profiles and their settlements from the scan index; an hourly refresh runs for tenants that have the program.

Field	Type	Notes
entityId	string	The entity row the agent is stored as (program `agents`).
name	string
chainId	integer \| null
agentId	string \| null	On-chain agent id from the scan index.
address	string \| null	Wallet address.
verificationStatus	string
screeningStatus	string \| null	Latest compliance-profile screening status, or null when never screened.
lastScreenedAt	string \| null (date-time)
settlements	integer	Transfers imported for this agent.
volumeCents	string	Sum of imported transfers. Integer cents as a string (bigint-safe).
skoor	integer \| null	Agent Risk Skoor (ars-v1); null until history is enough.
bandName	"clear" \| "review" \| "hold" \| "unscored"
n	integer
confidence	number \| null
version	string \| null

ImportResult

Field	Type	Notes
programId	string (uuid)
agents	integer
profiles	integer
settlementsScanned	integer
transfers	integer
counterparties	integer
agentCounterparties	integer

Endpoints

get/api/agents

Imported agents with their Skoors

Auth	Bearer + X-Operator
Operation	Agent · GET /api/agents

Parameters

Name	In	Type	Notes
tenant (optional)	query	string	Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit.

Responses

200 — Up to 500 agents on the tenant's agent program, newest update first. object

Field	Type	Notes
programId	string (uuid) \| null
lastImportAt	string (date-time) \| null
agents	Agent[]

401 — Bearer token missing or unknown. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

Example

curl -s "https://skoor.ai/risk/api/agents?tenant=demo" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Operator: you@bank.example"

post/api/agents/import

Import agents from the scan index

Auth	Bearer + X-Operator
Operation	Agent · POST /api/agents/import

Parameters

Name	In	Type	Notes
tenant (optional)	query	string	Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit.
Idempotency-Key (optional)	header	string	1–255 characters. A replay with the same body returns the stored status and body with `Idempotent-Replayed: true`; a different body under the same key is 409.

Request body (application/json) · object

Field	Type	Notes
limit (optional)	integer	Agents to import, 1–200 (default 50).
chainId (optional)	integer
offset (optional)	integer
txLimit (optional)	integer	Explorer settlements to scan for matches.
withProfiles (optional)	boolean	Fetch the compliance profile per agent.

Responses

201 — What was imported. ImportResult

Field	Type	Notes
programId	string (uuid)
agents	integer
profiles	integer
settlementsScanned	integer
transfers	integer
counterparties	integer
agentCounterparties	integer

401 — Bearer token missing or unknown. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

502 — Scan index unavailable; detail carries the upstream message. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

Example

curl -s -X POST "https://skoor.ai/risk/api/agents/import?tenant=demo" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Operator: you@bank.example" \
  -H "Content-Type: application/json" \
  -d '{"limit":50,"withProfiles":true}'

← All objects