curl -X POST https://win.oneshotagent.com/v1/tools/resolve/gene \
-H "Content-Type: application/json" \
-H "payment-signature: <base64 x402 payment>" \
-d '{
"query": "HER2"
}'
const response = await fetch("https://win.oneshotagent.com/v1/tools/resolve/gene", {
method: "POST",
headers: {
"Content-Type": "application/json",
"payment-signature": paymentProof,
},
body: JSON.stringify({
"query": "HER2"
}),
});
const result = await agent.tool('resolve/gene', {
query: 'HER2'
});
console.log(result.data.result);
console.log(result.data.evidence);
{
"success": true,
"data": {
"request_id": "uuid",
"receipt_id": "rcpt_...",
"status": "completed",
"tool": "gene_resolve",
"result": {
"matches": [
{
"gene_id": "2064",
"symbol": "ERBB2",
"name": "erb-b2 receptor tyrosine kinase 2",
"matched_on": "alias",
"aliases": [
"CD340",
"HER-2",
"HER-2/neu",
"HER2",
"MLN 19",
"MLN-19",
"NEU",
"NGL",
"TKR1",
"VSCN2",
"c-ERB-2",
"c-ERB2",
"p185(erbB2)"
],
"nomenclature_status": "official",
"organism": {
"scientific_name": "Homo sapiens",
"common_name": "human",
"taxon_id": 9606
},
"chromosome": "17",
"map_location": "17q12",
"page_url": "https://www.ncbi.nlm.nih.gov/gene/2064"
}
],
"ambiguous": false
},
"evidence": {
"source": "US National Center for Biotechnology Information",
"source_kind": "public",
"retrieved_at": "2026-10-17T12:00:00.000Z",
"calls": [
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
},
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
}
],
"as_of": null
}
}
}
Life sciences
Gene Resolve
Resolve a gene symbol, an alias or an Ensembl gene ID to NCBI Gene IDs, with official symbol, name, aliases and organism.
POST
/
v1
/
tools
/
resolve
/
gene
curl -X POST https://win.oneshotagent.com/v1/tools/resolve/gene \
-H "Content-Type: application/json" \
-H "payment-signature: <base64 x402 payment>" \
-d '{
"query": "HER2"
}'
const response = await fetch("https://win.oneshotagent.com/v1/tools/resolve/gene", {
method: "POST",
headers: {
"Content-Type": "application/json",
"payment-signature": paymentProof,
},
body: JSON.stringify({
"query": "HER2"
}),
});
const result = await agent.tool('resolve/gene', {
query: 'HER2'
});
console.log(result.data.result);
console.log(result.data.evidence);
{
"success": true,
"data": {
"request_id": "uuid",
"receipt_id": "rcpt_...",
"status": "completed",
"tool": "gene_resolve",
"result": {
"matches": [
{
"gene_id": "2064",
"symbol": "ERBB2",
"name": "erb-b2 receptor tyrosine kinase 2",
"matched_on": "alias",
"aliases": [
"CD340",
"HER-2",
"HER-2/neu",
"HER2",
"MLN 19",
"MLN-19",
"NEU",
"NGL",
"TKR1",
"VSCN2",
"c-ERB-2",
"c-ERB2",
"p185(erbB2)"
],
"nomenclature_status": "official",
"organism": {
"scientific_name": "Homo sapiens",
"common_name": "human",
"taxon_id": 9606
},
"chromosome": "17",
"map_location": "17q12",
"page_url": "https://www.ncbi.nlm.nih.gov/gene/2064"
}
],
"ambiguous": false
},
"evidence": {
"source": "US National Center for Biotechnology Information",
"source_kind": "public",
"retrieved_at": "2026-10-17T12:00:00.000Z",
"calls": [
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
},
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
}
],
"as_of": null
}
}
}
Give
query: an official gene symbol (TP53), an alias (P53, HER2) or an Ensembl gene ID (ENSG00000141510; a version suffix is dropped). Letters, digits, dots, dashes and _ only. taxon_id picks the organism and is human (9606) unless set. Returns the matching live genes, up to limit: genes whose official symbol is the query first, then genes that carry it as an alias, each in the source’s order, with the NCBI Gene ID (the input of Gene Summary), the symbol, the full name, the aliases, the nomenclature status, the organism, the chromosome, the cytogenetic band and the gene page link. matched_on says how each gene matched. A search hit that carries the query as neither its symbol nor an alias is dropped. ambiguous is true when more than one gene matched and none has the query as its official symbol. An unknown query returns an empty matches list. Replaced and discontinued Gene IDs are not returned. A query whose search finds more than 20 live records fails rather than returning a partial answer. Data from NCBI Gene at the US National Center for Biotechnology Information; official human symbols are assigned by the HUGO Gene Nomenclature Committee.
Authentication
Requires x402 payment in thepayment-signature header.
Request Body
string
required
An official gene symbol (TP53), an alias (P53, HER2) or an Ensembl gene ID (ENSG00000141510, a version suffix is dropped). 1 to 40 characters. Letters, digits, dots, dashes and
_ only, starting with a letter or digit.integer
The organism as an NCBI Taxonomy ID; 9606 (human) unless set, 10090 is mouse. From 1 to 999999999. Defaults to
9606.integer
The most matching genes to return. From 1 to 10. Defaults to
5.Response (200 OK)
Top-level envelope:success (boolean) and data (object). All fields below are nested under data.
string
Durable job ID for audit and lookup
string
Job status:
completedstring
Always
gene_resolveobject
The answer, described under Result below
object
Where the answer came from and when
string
The public body the data comes from. Always
US National Center for Biotechnology Information.string
public when the data comes from a public body, commercial otherwisestring
When the lookup was made, as an ISO 8601 UTC time
string
When the source says the fact was last updated, or
null when the source gives no dateResult
Nested underdata.result.
object[]
Matching live genes, official symbol matches first, then alias matches, up to limit.
string
The NCBI Gene ID, the input of Gene Summary.
string
The gene symbol.
null when the source gives no value.string
The full name.
null when the source gives no value.string
symbol, alias or ensembl: how the gene matched the query.
string[]
Other symbols the gene is known by.
string
Whether the symbol is official or interim; null when the source gives neither.
object
The organism the gene belongs to.
string
The organism’s scientific name, for example Homo sapiens.
null when the source gives no value.string
The organism’s common name, for example human.
null when the source gives no value.number
The organism’s NCBI Taxonomy ID.
null when the source gives no value.string
The chromosome, for example 17.
null when the source gives no value.string
The cytogenetic band, for example 17p13.1.
null when the source gives no value.string
The gene page URL.
boolean
True when more than one gene matched and none has the query as its official symbol, before applying limit.
curl -X POST https://win.oneshotagent.com/v1/tools/resolve/gene \
-H "Content-Type: application/json" \
-H "payment-signature: <base64 x402 payment>" \
-d '{
"query": "HER2"
}'
const response = await fetch("https://win.oneshotagent.com/v1/tools/resolve/gene", {
method: "POST",
headers: {
"Content-Type": "application/json",
"payment-signature": paymentProof,
},
body: JSON.stringify({
"query": "HER2"
}),
});
const result = await agent.tool('resolve/gene', {
query: 'HER2'
});
console.log(result.data.result);
console.log(result.data.evidence);
{
"success": true,
"data": {
"request_id": "uuid",
"receipt_id": "rcpt_...",
"status": "completed",
"tool": "gene_resolve",
"result": {
"matches": [
{
"gene_id": "2064",
"symbol": "ERBB2",
"name": "erb-b2 receptor tyrosine kinase 2",
"matched_on": "alias",
"aliases": [
"CD340",
"HER-2",
"HER-2/neu",
"HER2",
"MLN 19",
"MLN-19",
"NEU",
"NGL",
"TKR1",
"VSCN2",
"c-ERB-2",
"c-ERB2",
"p185(erbB2)"
],
"nomenclature_status": "official",
"organism": {
"scientific_name": "Homo sapiens",
"common_name": "human",
"taxon_id": 9606
},
"chromosome": "17",
"map_location": "17q12",
"page_url": "https://www.ncbi.nlm.nih.gov/gene/2064"
}
],
"ambiguous": false
},
"evidence": {
"source": "US National Center for Biotechnology Information",
"source_kind": "public",
"retrieved_at": "2026-10-17T12:00:00.000Z",
"calls": [
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
},
{
"retrieved_at": "2026-10-17T12:00:00.000Z"
}
],
"as_of": null
}
}
}
See Pricing for this tool’s price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers
200.Notes
- Results return inline. The finished job stays available at
/v1/requests/{request_id}