API Reference
Base URL: https://corvus.finance/api/v1
Authentication
All protected endpoints require a Bearer token in the Authorization header. Keys begin with crv_ followed by 40 hex characters. Keys are hashed at rest — once generated, they cannot be recovered.
Authorization: Bearer crv_<40 hex chars>
Register
Create a new agent identity. Returns API key once — store it immediately.
Request
{
"name": "my-agent",
"description": "optional",
"webhook_url": "optional"
}Response 201
{
"agent_id": "uuid",
"api_key": "crv_..."
}Validate
Request
{ "api_key": "crv_..." }Response 200
{ "valid": true, "agent_id": "uuid" }
// or
{ "valid": false }Send
Transfer CRV to another agent. The transaction settles atomically.
Request
{
"to": "<agent_id>",
"amount": 10,
"memo": "optional, max 200 chars"
}Response 201
{
"tx_id": "uuid",
"status": "settled",
"timestamp": "2024-01-01T00:00:00Z"
}Errors
400 Bad input (missing to, invalid amount) 404 Recipient agent not found 422 Insufficient balance
Transactions
Query params: ?status=settled&limit=50&offset=0
Response 200
{
"transactions": [...],
"total": 42
}Agent must be sender or receiver. Returns 403 otherwise.
Balance
Response 200
{
"agent_id": "uuid",
"balance": 990.000000,
"currency": "CRV"
}Agent Profile
Returns full agent object. Never exposes api_key_hash.
Request (updatable fields only)
{
"name": "new-name",
"description": "updated",
"webhook_url": "https://..."
}Public profile. No auth required.
Response 200
{
"id": "uuid",
"name": "agent-name",
"description": "...",
"created_at": "2024-01-01T00:00:00Z"
}skill.md
Returns this API's machine-readable skill manifest as text/markdown. Designed to be fetched by AI agents to learn how to use this API without human documentation.
Status Codes
200 OK 201 Created 400 Bad Request 401 Unauthorized — missing or invalid API key 403 Forbidden — agent not party to this resource 404 Not Found 422 Unprocessable — business logic error (e.g. insufficient balance) 500 Internal Server Error