# Pohjola API

Agent-native API for Finnish public company data via YTJ. Pay-per-call $0.01 USDC over x402. Available as REST and MCP.

Version: 0.1.0
Provider: Nousu Labs (https://github.com/nousulabs-debug/pohjola-api)

## Endpoints

- Agent card: `GET https://pohjola-api.nousulabs.workers.dev/.well-known/agent-card.json`
- MCP (JSON-RPC over HTTP): `POST https://pohjola-api.nousulabs.workers.dev/mcp`
- REST base: `https://pohjola-api.nousulabs.workers.dev/v1`

## Pricing

All paid endpoints settle in USDC on network `eip155:8453` via the x402 protocol.
Receiving address: `0x248773a449CC02A66C467235D84b689ace01e5d2`
Facilitator: `https://x402.org/facilitator`

## Tools

### ytj_company_lookup

Look up a Finnish company by Y-tunnus (business ID) from the YTJ Avoindata registry. Returns structured company information including name, status, legal entity type, and registration dates.

- REST: `GET /v1/ytj/lookup?id=<Y-tunnus>`
- MCP tool name: `ytj_company_lookup`
- Price: $0.01 USDC on eip155:8453

Example — unpaid request returns 402 with the payment requirements:

```
$ curl -i "https://pohjola-api.nousulabs.workers.dev/v1/ytj/lookup?id=2336509-6"
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "payTo": "0x248773a449CC02A66C467235D84b689ace01e5d2",
      "price": "$0.01",
      "currency": "USDC",
      "description": "Look up a Finnish company by Y-tunnus (business ID) from the YTJ Avoindata registry. Returns structured company information including name, status, legal entity type, and registration dates.",
      "mimeType": "application/json"
    }
  ]
}
```

Example — paid request:

```
$ curl -H "X-Payment: <x402-payment-payload>" "https://pohjola-api.nousulabs.workers.dev/v1/ytj/lookup?id=2336509-6"
```

## How x402 works

1. Call the endpoint without payment — the server replies 402 with an `accepts` array describing the required payment.
2. Sign an EIP-3009 USDC transfer authorization matching one of the accepts entries.
3. Resend the request with the signed authorization in the `X-Payment` header (base64-encoded JSON).
4. The server verifies via the facilitator, settles the payment, and returns the response.

See https://x402.org for payload signing.

## Source

https://github.com/nousulabs-debug/pohjola-api