Resolve a 10-digit NPI to the provider identity plus a fully decoded specialty profile in one call: entity type, name/organization, status, the primary specialty (NUCC grouping + classification + display name), and every taxonomy on the record decoded the same way -- with primary flag, practice state, and license. Combines the NPPES lookup (medical.npi) with the NUCC specialty decode (medical.taxonomy-specialty) so a claims, credentialing, or referral agent gets "who is this NPI and what do they actually do" without a second call. Data: CMS NPPES + NUCC (US public domain). Note: the facility CCN (CMS Certification Number) requires a separate CMS enrollment crosswalk and is returned null (DEFERRED) rather than guessed.
/api/medical/provider-id-resolvePAYMENT-SIGNATURE.The provider id resolve API is a pay-per-call medical endpoint built for AI agents and autonomous software. Resolve a 10-digit NPI to the provider identity plus a fully decoded specialty profile in one call: entity type, name/organization, status, the primary specialty (NUCC grouping + classification + display name), and every taxonomy on the record decoded the same way -- with primary flag, practice state, and license.
There is no signup and no API key. An agent (or any HTTP client) hits the endpoint, receives an x402 "402 Payment Required" challenge, signs a sub-cent USDC payment on Base or Solana, and retries — the data comes back on the paid request. That makes it a drop-in provider id resolve data source for an agent tool-use loop, an MCP host, or a backend that needs medical data on demand without onboarding to yet another vendor portal.
| Name | Type | Description |
|---|---|---|
npirequired | string | 10-digit National Provider Identifier. match ^\d{10}$ |
# 1. Probe with no auth → 402 envelope with PaymentRequirements curl -sS 'https://2s.io/api/medical/provider-id-resolve?npi=12345' # 2. Sign + retry with PAYMENT-SIGNATURE: curl -sS 'https://2s.io/api/medical/provider-id-resolve?npi=12345' \ -H 'PAYMENT-SIGNATURE: <base64-json-payload>' # Or use the canonical runner (handles probe → sign → retry): # EVM_PRIVATE_KEY=0x... node --env-file=.env.local \ # --experimental-strip-types scripts/x402-pay.ts \ # 'https://2s.io/api/medical/provider-id-resolve?npi=12345'
import { TwoS } from '@2sio/sdk'
const client = new TwoS({
privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})
const result = await client.medical.providerIdResolve({
"npi": "12345"
})
console.log('endpoint:', result.endpoint)
console.log('cost:', result.costUsd, 'USDC')
console.log('tx:', result.settlement?.txHash)
console.log('data:', result.data)import os
from twosio import TwoS
client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])
result = client.medical.provider_id_resolve(npi="12345")
print("endpoint:", result.endpoint)
print("cost:", result.cost_usd, "USDC")
print("tx:", (result.settlement or {}).get("tx_hash"))
print("data:", result.data)// 1. Add @2sio/mcp to your MCP host config (Claude Desktop example below).
// EVM_PRIVATE_KEY funds x402 payments per call.
// claude_desktop_config.json
{
"mcpServers": {
"2sio": {
"command": "npx",
"args": ["-y", "@2sio/mcp"],
"env": { "EVM_PRIVATE_KEY": "0x..." }
}
}
}
// 2. Once the server is running, agents call this tool via standard MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "medical.provider-id-resolve",
"arguments": {
"npi": "12345"
}
}
}| Field | Type | Description |
|---|---|---|
ok | boolean | one of: true |
items | array | |
total | integer | Total matching rows upstream; null when unknown. |
source | object |
{
"ok": true,
"items": [
{
"npi": "example",
"entityType": "example",
"name": "example",
"organizationName": "example",
"status": "example",
"primarySpecialty": {
"code": "example",
"grouping": "example",
"classification": "example",
"displayName": "example"
},
"taxonomies": [
{
"code": "example",
"primary": false,
"state": "example",
"license": "example",
"grouping": "example",
"classification": "example",
"specialization": "example",
"displayName": "example"
}
],
"ccn": "null"
}
],
"total": 1,
"source": {
"provider": "example",
"url": "example",
"license": "example"
}
}