US Tax Treaty API: Bilateral Treaties and Technical Explanations as Data

US bilateral income tax treaties, together with Treasury's Technical Explanations, are available as a queryable corpus behind corpusType=US_TAX_TREATY: 173 IRS-sourced documents (conventions, protocols and Technical Explanations), plus 1,476 Senate treaty records on the same token. The point of putting them behind an API is retrieval by meaning. Nobody reads a treaty end to end. They look for the royalties article, or the Limitation on Benefits article, and a search that returns the right instrument with the matching passage around it beats a link to a 40-page PDF. If you are building for cross-border tax, transfer pricing, or a payroll or payments platform that has to decide a withholding rate at runtime, that is where the time goes.

Reviewed and corrected on 12 October 2026. This is general information, not legal advice.

TL;DR

• 173 IRS-sourced documents plus 1,476 Senate treaty records, corpusType=US_TAX_TREATY. The IRS-sourced documents are the treaty texts, protocols and Treasury's Technical Explanations. The Senate records (treaty transmittals, resolutions of advice and consent, and Treaty Documents) share the token and are separated by the source filter.
• Each item is a whole instrument. A search returns the treaty or Technical Explanation that matches, with an excerpt around the matching passage. You read the article number from the text, not from a field.
• A Technical Explanation is Treasury's own guide to a convention. Treasury's explanation of the 1996 US-Thailand convention calls it "an official guide to the Convention," reflecting "the policies behind particular Convention provisions, as well as understandings reached with respect to the application and interpretation of the Convention." Practitioners lean on it hard.
• Article numbering is not standard across treaties. In the 1994 US-Portugal convention Royalties is Article 13 and Limitation on Benefits is Article 17. In the 1996 US-Thailand convention they are Articles 12 and 18. That is why you query the specific treaty instead of hardcoding a number.
• A treaty alone is never the answer. A real position needs the article, the Technical Explanation, the Internal Revenue Code section in Title 26, and the Treasury Regulations in 26 CFR, and those interact through the later-in-time rule and the treaty's own saving clause.
• Deliberately not here: the OECD Model and its Commentary (not US primary law), competent authority agreements, and any foreign country's domestic tax law.

One of the source-by-source entries in our US primary law corpus series.

The fourth corpus in the sequence below has its own post: the IRS guidance API guide. For the Treasury Regulations side, see the CFR API guide.

How these numbers were measured

The 173 and 1,476 are the figures our coverage notes carry for this token (the live count of the whole token on 12 October 2026 was 1,665, which is higher because the corpus keeps growing). GET /us/statutes/coverage is free, returns per-corpus counts with a measuredAt stamp, and is the endpoint to call before you trust anything in this post. The coverage reference describes it. We build this API, so verify rather than take our word for it.

Legal propositions carry their citation inline. Nothing here is tax advice, and a treaty position is a lawyer's call, not an API response.

A short history: from a 1932 French treaty to a treaty corpus

The first US income tax treaty was signed in Paris on April 27, 1932, with France (the State Department's record of the convention lists it as a convention and protocol on double taxation). Avi-Yonah's history of US treaty policy describes what it did: the treaty "reduced US withholding taxes at a time when France was a purely territorial jurisdiction, which meant that US source income would be taxed neither by the US nor by France" (University of Michigan Law repository).

A treaty starts as a negotiated fix for a specific mismatch between two tax systems. That helps explain why no two of them read alike and why a rate you learned for one country tells you little about another.

The status of any one treaty also isn't a yes-or-no field. The IRS's A to Z list of income tax treaties (page last reviewed 3 January 2026) marks Belarus and Russia "CAUTION Treaty Partially Suspended" and Hungary "CAUTION Treaty Terminated." If your product shows a treaty rate, a flag like that belongs next to it.

Why a treaty needs more than a link

Treasury and the IRS publish each treaty as a document. That is correct for a treaty and awkward for software.

Consider what a cross-border question actually looks like. A payments platform is about to pay a software license fee to a company in another country and has to decide the withholding rate. That decision turns on one article, the royalties article, and possibly on the Limitation on Benefits article that determines whether the recipient qualifies for treaty benefits at all.

The platform doesn't want to read a 40-page PDF to find them. It wants the right instrument, a stable id, the passage that matches, and the official source URL so a human can check it. That is the shape of a result here: a document with a sourceUrl on treasury.gov or irs.gov, and an excerpt around the passage that matched.

What a Technical Explanation is, and why practitioners rely on it

Treasury publishes a Technical Explanation alongside a signed treaty or protocol. Its treaty page says that treaty documents "are posted on this site upon signature and prior to ratification and entry into force." The Technical Explanation walks the convention article by article and says what the negotiated language means.

This isn't a summary and it isn't commentary from a publisher. It is the executive branch's own account of what it agreed to, written by the department that negotiated it. Treasury's explanation of the US-Thailand convention opens by calling itself "an official guide to the Convention."

That provenance is why practitioners treat it the way they treat legislative history for a statute. When treaty text is ambiguous, the Technical Explanation is usually the first place anybody looks.

For a developer, the practical consequence is that a treaty and its Technical Explanation are two documents that must be retrievable as a pair. In this corpus they are separate items with separate actId values, for example TREATY_US_VENEZUELA_1999 for the Venezuela convention and TREATY_US_ITALY_TE_19991022 for the Italy Technical Explanation. A tool that returns the treaty and drops the explanation has done the easy half.

Signature is not force

Be precise about the lifecycle, because it trips people up. Treasury's explanation of the US-Thailand convention describes the US process: once a treaty is signed, the State Department sends it to the President, who formally transmits it to the Senate for its advice and consent to ratification, which requires approval by two-thirds of the Senators present and voting. After that the treaty goes back to the President to sign the ratification document, and the convention "will enter into force upon the exchange of instruments of ratification." The same text adds a point that matters for software: "The date on which a treaty enters into force is not necessarily the date on which its provisions take effect." Effective dates for particular taxes can lag entry into force by a period the treaty itself sets.

Signature isn't force. A signed protocol can sit for a long time before it does anything to a withholding rate.

The interaction with domestic law

A treaty doesn't float above the Internal Revenue Code, and the Code doesn't override the treaty by default. They interact through two mechanisms that any serious cross-border tool has to represent.

The later-in-time rule. A treaty and a federal statute occupy the same rung, so where they genuinely conflict, the later-enacted one controls. Congress said this explicitly for tax at 26 U.S.C. § 7852(d)(1), which provides that neither a treaty nor a law has preferential status by reason of its being a treaty or a law. The underlying constitutional principle traces to Whitney v. Robertson, 124 U.S. 190 (1888).

The Supreme Court laid out the later-in-time idea in Whitney v. Robertson, a sugar tariff case decided on January 9, 1888. Justice Field wrote that a treaty and a statute are both "the supreme law of the land, and no superior efficacy is given to either over the other." He also gave the tiebreaker: "if the two are inconsistent, the one last in date will control the other, provided always the stipulation of the treaty on the subject is self-executing." The full opinion is at the Library of Congress. Note the middle of that passage, which is easy to skip: courts first try to read the two together, and the self-executing condition matters.

The saving clause. Most US income tax treaties contain one, and the IRS says so on its treaty page: "Most income tax treaties contain what is known as a 'saving clause'." Treasury's explanation of the US-Thailand convention describes it as "the traditional saving clause found in all U.S. treaties" and says the contracting states "reserve their rights, except as provided in paragraph 3, to tax their residents and citizens as provided in their internal laws, notwithstanding any provisions of the Convention to the contrary." The exceptions are listed inside the clause itself.

That is where most naive tools go wrong. A model that reads "Article 15 says employment income is taxable only in the residence state" and stops has skipped the clause that pulls US persons back out of the benefit. The exceptions list inside the saving clause is the part that decides the answer.

Two Code provisions round out the picture. 26 U.S.C. § 894(a)(1) provides that the Code "shall be applied to any taxpayer with due regard to any treaty obligation of the United States which applies to such taxpayer." 26 U.S.C. § 6114 requires a taxpayer who takes the position that a treaty overrules or modifies an internal revenue law to disclose that position, with the mechanics in 26 CFR § 301.6114-1.

What people say about the saving clause

If you want to know where the saving clause bites, read what non-lawyers write when it surprises them. In October 2021 a Hacker News commenter named estewart explained why renouncing is harder than people expect: the US-Netherlands treaty has a saving clause "which basically states, regardless of what else is in the treaty, nothing will stop the U.S. from taxing the US person based on US laws as though the treaty did not exist, except for specified circumstances" (Hacker News, October 2021). That's a layperson's paraphrase, and it matches what Treasury's explanation of the Thailand convention says about the clause.

Another commenter, pembrook, writing about expat taxes in 2018, put the practical result this way: "In general these treaties protect foreign nationals living in the US from double taxation much more than US citizens living abroad." (Hacker News, June 2018). Whatever you think of the policy, it's a good test case for software. A tool that tells a US citizen "the treaty says X" and skips the saving clause has told them half the story.

The worked query sequence, across four corpora

Requests go to https://api.vaquill.ai/api/v1/us/statutes/* with a bearer key. A search is 4 credits and coverage is free. The result fields shown below come from real responses on 12 October 2026; the requests need a key, so we did not run the curl commands as written.

Step 0. See what is there.

curl -s https://api.vaquill.ai/api/v1/us/statutes/coverage \
  -H "Authorization: Bearer vq_key_..."

Coverage is worth calling here for one reason: the count. Because a treaty and its Technical Explanation are separate items, and the Senate records share the token, the count is not a number of countries, and coverage is where you enumerate what is actually present instead of guessing.

Step 1. Find the instrument.

curl -s -X POST https://api.vaquill.ai/api/v1/us/statutes/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "royalties withholding rate industrial equipment",
    "corpusType": "US_TAX_TREATY",
    "limit": 10
  }'

Search is hybrid, running semantic and keyword retrieval together, a design our hybrid search guide explains. Treaty language is stilted and old ("payments of any kind received as a consideration for the use of, or the right to use..."), so the semantic half matters more here than in most corpora. Users ask about "royalty withholding" and the document says something else entirely.

The first three results on 12 October 2026, trimmed, show the shape (the API rated the match quality weak for that loose query, which is worth reading before you trust a result):

{ "actId": "TREATY_US_ITALY_TE_19991022", "citation": "U.S.-Italy Tax Treaty Technical Explanation (1999)",
  "source": "us_tax_treaty_technical_explanation", "documentTypeLabel": "technical_explanation", "wordCount": 53292,
  "sourceUrl": "https://home.treasury.gov/system/files/131/Treaty-Italy-TE-10-22-1999.pdf" }
{ "actId": "TREATY_US_SPAIN_TE_1990", "citation": "U.S.-Spain Tax Treaty Technical Explanation (1990)",
  "source": "us_tax_treaty_technical_explanation", "documentTypeLabel": "technical_explanation", "wordCount": 24987,
  "sourceUrl": "https://www.irs.gov/pub/irs-trty/spain-te-1990.pdf" }
{ "actId": "TREATY_US_VENEZUELA_1999", "citation": "U.S.-Venezuela Income Tax Treaty (1999)",
  "source": "us_tax_treaty", "documentTypeLabel": "treaty", "wordCount": 14626,
  "sourceUrl": "https://www.irs.gov/pub/irs-trty/venezu.pdf" }

Each result also carries an excerpt around the passage that matched. Narrow a query to one instrument type with source (us_tax_treaty or us_tax_treaty_technical_explanation).

Step 2. Pull the document, then find the article in it.

curl -s "https://api.vaquill.ai/api/v1/us/statutes/section/{actId}/body" \
  -H "Authorization: Bearer vq_key_..."

Take the actId from the search response and store it. The treaty ids look readable, but the API's guidance is to echo ids from a response and not build them. The body is the whole instrument, so find the royalties article in the text and record its number for that treaty. Every result carries a sourceUrl for the publisher's own copy, so a reviewer can open Treasury's or the IRS's version of the same text.

Step 3. Get the Code section.

-d '{
  "query": "withholding of tax on nonresident aliens",
  "corpusType": "USC",
  "titleNumber": 26,
  "limit": 5
}'

Title 26 lives inside the USC corpus (60,494 sections in all), and each section reports its own currentThrough date.

Step 4. Get the regulation.

-d '{
  "query": "claim of reduced withholding under an income tax treaty",
  "corpusType": "CFR",
  "titleNumber": 26,
  "limit": 5
}'

The CFR corpus is 222,311 sections and refreshes daily, which is the piece of this chain that moves most often.

Step 5. Get the administrative guidance.

-d '{
  "query": "treaty benefit documentation procedure",
  "corpusType": "AGENCY_GUIDANCE",
  "source": "irs_rev_proc",
  "limit": 5
}'

IRS revenue procedures, revenue rulings, notices, and announcements sit under AGENCY_GUIDANCE with the source codes irs_rev_proc, irs_rev_rul, irs_notice, and irs_announcement. We have a separate post in this series on querying IRS guidance as data.

Five calls, one schema, one actId convention, and a citation at every step. Unknown filter values return 422 rather than silently matching nothing, so a typo fails loudly. Each page of a search is a new call.

The four-corpus table

Those four are the answer, and each token in the corpusType column is defined in the corpus types reference. A tool that serves only the first one is a document viewer with extra steps. The last row is unpacked in the IRS guidance API guide, and the Treasury Regulations row in the CFR API guide.

The version problem, stated honestly

Every citation here maps to one stored text, the one the corpus holds now. The section body call takes asOf=YYYY-MM-DD, but for this corpus the answer is a reconstruction rebuilt from the first change we observed after your date, and the asOf block says so (engine: observed_change). isBounded: true means we observed no change affecting your date, which is not the same as there having been none, because capture began after the corpus did. It isn't an archive of superseded treaty texts. Amendment History and Point-in-Time Law: What a Legal API Can and Cannot Tell You is the fuller argument for why.

For tax that is a real constraint, because a return position for an earlier year runs on the text in force for that year, and a protocol may have replaced an article since. Say this plainly in your product rather than letting a user assume a reconstruction is the text a return filed for that year relied on.

What you do get: the per-section change history (GET /us/statutes/section/{actId}/changes), a lastAmendedYear field and yearFrom and yearTo currency filters. Those tell you that something changed and when, which is enough to route a human to the right archived document, and they aren't a substitute for serving the old text. One caveat on the year filters everywhere in the API: they filter on the last amendment year the publisher credits, so they track the law rather than our rebuild date. About a fifth of sections across the whole corpus carry no amendment credit at all, because some publishers print none, and those drop out of results once either bound is set.

Who this is wrong for

The OECD Model Commentary sits outside this corpus by design. It is an influential interpretive reference rather than US primary law.

The other country's domestic law is the other half of a treaty analysis, and it lives in a foreign jurisdiction rather than in a US primary law corpus.

If your workflow depends on competent authority agreements or on the Senate committee record, those are separate documents and they aren't in this corpus.

And if you want a rate lookup that returns a single number for a country and a payment type, that is a layer you build on top of these calls. We serve the law; the arithmetic and the qualification analysis, Limitation on Benefits included, are yours.

Where the corpus sits

Federal law totals about 1.5 million sections inside a corpus of more than 5.3 million sections across 56 state-level jurisdictions and federal law.

The source for each corpus is the government publisher's own copy; for this one that means treasury.gov, irs.gov and congress.gov. The same surface is available to agents over MCP at mcp.vaquill.ai. We build the Vaquill AI primary law API, and the collection layer behind it is published at open-us-law.

FAQ

What is in the US tax treaty corpus?

173 IRS-sourced documents behind corpusType=US_TAX_TREATY, covering US income tax conventions, protocols and Treasury's Technical Explanations, plus 1,476 Senate treaty records (transmittals, resolutions of advice and consent, and Treaty Documents) on the same token. Because a treaty and its Technical Explanation are separate items, the item count is larger than the number of countries covered.

What is a Technical Explanation and does it bind anyone?

It is Treasury's article-by-article guide to a convention, written by the department that negotiated it. Treasury's explanation of the US-Thailand convention calls it "an official guide to the Convention." It isn't the treaty and it doesn't bind a court, but it is the closest thing a treaty has to legislative history and it is where practitioners look first when text is ambiguous.

Can I look up a treaty article by number?

Not as a field. Each item is a whole instrument, so search for the concept and read the article number off the text. Article numbering varies across treaties: Royalties is Article 12 in the 1996 US-Thailand convention and Article 13 in the 1994 US-Portugal convention, and Limitation on Benefits is Article 18 and Article 17 respectively.

How does a tax treaty interact with the Internal Revenue Code?

Through the later-in-time rule and the saving clause. Neither instrument has automatic priority, which Congress made explicit at 26 U.S.C. § 7852(d)(1), and the constitutional principle traces to Whitney v. Robertson, 124 U.S. 190 (1888). Separately, the saving clause in most US treaties lets the United States tax its own citizens and residents as provided in its internal laws, subject to the exceptions listed inside the clause.

Is the OECD Model Tax Convention included?

No. The OECD Model and its Commentary are drafting and interpretive references rather than US primary law. Competent authority agreements and any foreign country's domestic tax law are also out of scope.

Can I retrieve the version of a treaty that applied in an earlier year?

For this corpus, asOf=YYYY-MM-DD is a reconstruction: the earlier text is rebuilt from the first change observed after your date, and isBounded: true means only that no change affecting your date was observed. It is not an archive of superseded treaty texts, so confirm an earlier year's text against the IRS or Treasury copy before you rely on it.

What corpora do I need for a full cross-border answer?

Four. The treaty and its Technical Explanation in US_TAX_TREATY, the Code section under corpusType=USC with titleNumber=26, the Treasury Regulation under corpusType=CFR with titleNumber=26, and IRS administrative guidance under AGENCY_GUIDANCE with source=irs_rev_proc or its sibling codes.

How much does this cost per query?

A search call is 4 credits, per the live pricing endpoint on 12 October 2026. GET /us/statutes/coverage and GET /boards are free, failed calls aren't charged, and each page of a search is a new call at the same price.

Does signing a treaty change the withholding rate right away?

No. Signature is followed by transmittal to the Senate, advice and consent, the President's signature on the ratification document and the exchange of instruments, at which point the convention enters into force. Effective dates for particular taxes can lag entry into force by a period the treaty specifies. Model signature, entry into force, and effective date as separate fields, or your platform will apply a rate that isn't yet in effect.

Are estate and gift tax treaties covered too?

Not verified in our October 2026 review. The IRS-sourced items we checked are income tax conventions. Search for the specific treaty you need, or check the IRS and Treasury treaty pages directly, before assuming a counterpart exists for a given country.

Priyansh Khodiyar

Co-Founder & CTO

Priyansh leads engineering and AI at Vaquill AI: the pipelines that pull statutes, regulations and court rules from every US jurisdiction's official publisher, and the REST API, MCP server and open dataset that serve them.