# namegen

> Random personal names typical of a region. Synthetic output for fiction, placeholders and test data.

## Quickstart
GET https://namegen-diegouqz.fly.dev/v1/names?region=AR&count=3&gender=any

## Parameters
- region (required): ISO 3166-1 alpha-2. Supported: AR, BR, CN, DE, ES, FR, GB, IN, IT, JP, MX, NG, US
- count: 1-100 (default 1)
- gender: any | male | female (default any)
- seed: optional string, makes output reproducible

## Response (schema namegen.v1)
{"schema":"namegen.v1","region":"AR","count":1,"synthetic":true,
 "results":[{"full_name":"...","given_name":"...","family_names":["..."],"gender":"...","locale":"es-AR"}]}

## Errors
JSON {"error":{"code":"REGION_UNSUPPORTED","message":"...","hint":"..."}}
Codes: REGION_REQUIRED, REGION_UNSUPPORTED, COUNT_INVALID, COUNT_OUT_OF_RANGE, GENDER_INVALID

## Machine-readable
- OpenAPI: https://namegen-diegouqz.fly.dev/openapi.json
- Agent card: https://namegen-diegouqz.fly.dev/.well-known/agent.json
- MCP (remote, streamable HTTP): https://namegen-diegouqz.fly.dev/mcp  (tools: generate_names, list_regions)
- MCP (local, stdio): python -m namegen.mcp_server

## Payment (x402, pay-what-you-want)
- /v1/names costs at least 0.10 USDC per request, paid in USDC on base.
- To pay more, add `pay=<amount>` (e.g. `&pay=0.25`). Omit it to pay the minimum.
- First call returns HTTP 402 with `accepts` (payTo, asset, maxAmountRequired).
- Sign the payment with an x402 client and retry the SAME URL with header `X-PAYMENT`.
- Price errors: PAY_INVALID, PAY_BELOW_MINIMUM, PAY_ABOVE_MAXIMUM (HTTP 400, nothing charged).
- Free: /v1/regions, /openapi.json, /llms.txt, /.well-known/agent.json

## Usage policy
Names are random combinations, not real people or identities. Do not use them to impersonate,
create accounts under a fake persona, or pass identity checks.