ExchangeRebel Address Verdicts API

openapi: 3.2.0
info:
  title: ExchangeRebel — pay-per-call APIs for AI agents (x402 on…
  version: 1.0.0
  contact:
    name: 'ExchangeRebel (operator: Rebel Data)'
    url: https://exchangerebel.com
    email: sound.money.investing@gmail.com
  x-guidance: 'All paid operations use x402 on Solana: call without payment to get a 402 challenge (SOL recipient + USDC token account + fresh memo), pay with the memo attached via the Solana Memo program, then retry with header X-Payment-Tx: <signature> and ?toll_memo=<memo>. Challenges are dual-version: the PAYMENT-REQUIRED header carries the x402 v2 PaymentRequired object and the response body carries the same challenge in x402 v1 form for compatibility. Free operations (security: []) include each service''s /health catalog with full response shapes. Prices in x-payment-info are USD per call unless the summary says otherwise (RPC is per 1,000-request block; Telegram provisioning is per bot-month; transcription is per minute of audio).'
  description: '67 data and utility APIs behind x402 tolls, settled in SOL or USDC on Solana. Call a paid endpoint without payment to receive a 402 x402 challenge (recipient + fresh memo), pay with the memo attached via the Solana Memo program, then retry with the X-Payment-Tx header and toll_memo query parameter. Free catalog/health endpoints are marked without x-payment-info. Full catalogs: GET /toll/discovery and each service''s /health.'
servers:
- url: https://exchangerebel.com
tags:
- name: Address Verdicts
paths:
  /toll/address/verify:
    post:
      tags:
      - Address Verdicts
      summary: Verify an address in 1-4 countries
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
          content:
            application/json:
              example:
                ok: true
                paid_with: onchain
                address_queried:
                  unit: Unit 2
                  street_number: '134'
                  street_name: Bandjalong
                  street_type: Crescent
                  locality: Aranda
                  state: ACT
                  postcode: '2614'
                countries:
                - AU
                results:
                - country: AU
                  verdict: verified
                  normalised_address:
                    unit: '2'
                    street_number: '134'
                    street_name: BANDJALONG
                    street_type: CRESCENT
                    locality: ARANDA
                    state: ACT
                    postcode: '2614'
                    geocode:
                      lat: -35.2594636
                      lon: 149.08584521
                  confidence: 1
                  provenance:
                    source: Geoscape G-NAF (Geocoded National Address File) — Standard PSV tables joined (ADDRESS_DETAIL + STREET_LOCALITY + LOCALITY + ADDRESS_DEFAULT_GEOCODE)
                    source_vintage: August 2026 release
                    method: file_match_gnaf_standard_join
                    attribution: Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement
                envelope:
                  v: 1
                  service: address-verdicts
                  as_of: '2026-08-01T00:00:00.000Z'
                  source: Geoscape G-NAF (Geocoded National Address File) — Standard PSV tables joined (ADDRESS_DETAIL + STREET_LOCALITY + LOCALITY + ADDRESS_DEFAULT_GEOCODE)
                  grade: official
                  changes:
                    supported: false
        '402':
          description: 'Payment Required (x402). The PAYMENT-REQUIRED response header carries the x402 v2 PaymentRequired object (base64 JSON: scheme, CAIP-2 network, amount, asset, payTo, plus the bazaar discovery extension); the response body carries the same challenge in x402 v1 form for compatibility, naming the SOL recipient and USDC token account on Solana plus a fresh memo. To pay on this service''s rail: pay with the memo attached (Solana Memo program), then retry with header ''X-Payment-Tx: <transaction signature>'' and query parameter ''toll_memo=<memo>''.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
                country:
                  type: string
                  description: string - one country code (AU, US, CA, FR); supply either country or countries, not both
                countries:
                  type: array
                  description: array of strings - 1 to 4 country codes; each additional country beyond the first adds $0.005 to the call price
                  items:
                    type: string
              required:
              - address
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
      security:
      - x402Payment: []
      operationId: postTollAddressVerify
      x-operation-id-source: derived
  /toll/address/countries:
    get:
      tags:
      - Address Verdicts
      summary: Address verdict country catalog + honesty
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      security: []
      operationId: getTollAddressCountries
      x-operation-id-source: derived
  /toll/address/health:
    get:
      tags:
      - Address Verdicts
      summary: Check the address verdicts service status
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      security: []
      operationId: getTollAddressHealth
      x-operation-id-source: derived
  /toll/address/legs/nl/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'Netherlands address leg: matched / partial / no_match'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
          content:
            application/json:
              example:
                ok: true
                paid_with: onchain
                leg: nl
                country: NL
                address_queried:
                  street_number: '19'
                  street_name: Binnenhof
                  locality: Den Haag
                  postcode: 2513 AA
                result:
                  leg: nl
                  country: NL
                  verdict: partial
                  matched_components:
                    street_number: '19'
                    street_name: Binnenhof
                    locality: '''s-Gravenhage'
                    postcode: 2513AA
                  provenance:
                    source: BAG via PDOK Locatieserver
                    licence: CC BY 4.0
                    attribution: 'Source: BAG via PDOK Locatieserver. Licence: CC BY 4.0.'
                    method: live_api_pdok_locatieserver
                    source_access: live_api
                  honest_limits:
                  - A free official service exists for this source (the PDOK Locatieserver over the BAG register) and is disclosed here; what this leg sells is the one-schema toll-gated shape and bundle fan-out.
                  - Existence and normalisation verdicts only; no answer states or implies that post can be received at an address.
                  - 'No confidence or score is returned: no score field is on record for this source.'
                envelope:
                  v: 1
                  service: address-verdicts
                  grade: official
                  changes:
                    supported: false
        '402':
          description: 'Payment Required (x402). The PAYMENT-REQUIRED response header carries the x402 v2 PaymentRequired object (base64 JSON: scheme, CAIP-2 network, amount, asset, payTo, plus the bazaar discovery extension); the response body carries the same challenge in x402 v1 form for compatibility, naming the SOL recipient and USDC token account on Solana plus a fresh memo. To pay on this service''s rail: pay with the memo attached (Solana Memo program), then retry with header ''X-Payment-Tx: <transaction signature>'' and query parameter ''toll_memo=<memo>''.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
      security:
      - x402Payment: []
      operationId: postTollAddressLegsNlValidate
      x-operation-id-source: derived
  /toll/address/legs/us/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'US address leg: range_match / no_match, range kept'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
          content:
            application/json:
              example:
                ok: true
                paid_with: onchain
                leg: us
                country: US
                address_queried:
                  street_number: '4600'
                  street_name: Silver Hill
                  street_type: Rd
                  locality: Washington
                  state: DC
                  postcode: '20233'
                result:
                  leg: us
                  country: US
                  verdict: range_match
                  matched_address: 4600 SILVER HILL RD, WASHINGTON, DC, 20233
                  matched_components:
                    house_number_range_from: '4600'
                    house_number_range_to: '4700'
                    street_name: SILVER HILL
                    street_type: RD
                    locality: WASHINGTON
                    state: DC
                    postcode: '20233'
                  geocode:
                    lat: 38.84505589808
                    lon: -76.92836638093
                    interpolated: true
                  tiger_line:
                    id: '657091557'
                    side: L
                  provenance:
                    source: U.S. Census Bureau — Census Geocoder
                    licence: Census Bureau API Terms of Service
                    attribution: This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.
                    method: live_api_census_geocoder
                    source_access: live_api
                  honest_limits:
                  - 'A match from this leg is a range match, not an existence verdict: the Geocoder''s address ranges include all possible structure numbers even though actual structures may not exist.'
                  - 'Coordinates are interpolated along the address range and are labelled interpolated: true in every answer.'
                  - The Census Geocoder is a free official service; what this leg sells is the one-schema toll-gated shape and bundle fan-out.
                  - 'No confidence or score is returned: no returned score field is on record for this source.'
                  - This leg never uses or combines data to identify a person, household or business; it answers only about the address supplied.
                envelope:
                  v: 1
                  service: address-verdicts
                  grade: official
                  changes:
                    supported: false
        '402':
          description: 'Payment Required (x402). The PAYMENT-REQUIRED response header carries the x402 v2 PaymentRequired object (base64 JSON: scheme, CAIP-2 network, amount, asset, payTo, plus the bazaar discovery extension); the response body carries the same challenge in x402 v1 form for compatibility, naming the SOL recipient and USDC token account on Solana plus a fresh memo. To pay on this service''s rail: pay with the memo attached (Solana Memo program), then retry with header ''X-Payment-Tx: <transaction signature>'' and query parameter ''toll_memo=<memo>''.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.005'
      security:
      - x402Payment: []
      operationId: postTollAddressLegsUsValidate
      x-operation-id-source: derived
  /toll/address/bundle/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'Address bundle: fan out to 2-3 live legs, flat $0.01'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
          content:
            application/json:
              example:
                ok: true
                paid_with: onchain
                address_queried:
                  unit: '2201'
                  street_number: '183'
                  street_name: Wellington W
                  street_type: ST
                  locality: Toronto
                  state: 'ON'
                  postcode: M5V 0A1
                legs_requested:
                - ca
                - nl
                results:
                - leg: ca
                  country: CA
                  verdict: verified
                  normalised_address:
                    unit: '2201'
                    street_number: '183'
                    street_name: WELLINGTON W
                    street_type: ST
                    locality: TORONTO
                    state: 'ON'
                    postcode: M5V0A1
                    geocode:
                      lat: 43.64565
                      lon: -79.386943
                  confidence: 1
                  provenance:
                    source: Statistics Canada — National Address Register (NAR), catalogue 46-26-0002
                    source_vintage: June 2026 release (202606)
                    method: file_match_nar_extract
                    attribution: Adapted from Statistics Canada, National Address Register, June 2026. This does not constitute an endorsement by Statistics Canada of this product.
                    source_access: ingested_file
                  honest_limits:
                  - 'Canada is a bundle member in the legs service: it is served inside the bundle fan-out by the same NAR file matcher that powers the live /verify op, and the standalone leg path refuses free (see DESIGN §3.3).'
                  - Existence and normalisation verdicts only; no answer states or implies that post can be received at an address.
                - leg: nl
                  country: NL
                  verdict: no_match
                  matched_components: null
                  provenance:
                    source: BAG via PDOK Locatieserver
                    licence: CC BY 4.0
                    attribution: 'Source: BAG via PDOK Locatieserver. Licence: CC BY 4.0.'
                    method: live_api_pdok_locatieserver
                    source_access: live_api
                  honest_limits:
                  - A free official service exists for this source (the PDOK Locatieserver over the BAG register) and is disclosed here; what this leg sells is the one-schema toll-gated shape and bundle fan-out.
                  - Existence and normalisation verdicts only; no answer states or implies that post can be received at an address.
                  - 'No confidence or score is returned: no score field is on record for this source.'
                envelope:
                  v: 1
                  service: address-verdicts
                  as_of: '2026-10-21T21:19:58.442Z'
                  source: Statistics Canada — National Address Register (NAR), catalogue 46-26-0002; BAG via PDOK Locatieserver
                  grade: official
                  changes:
                    supported: false
        '402':
          description: 'Payment Required (x402). The PAYMENT-REQUIRED response header carries the x402 v2 PaymentRequired object (base64 JSON: scheme, CAIP-2 network, amount, asset, payTo, plus the bazaar discovery extension); the response body carries the same challenge in x402 v1 form for compatibility, naming the SOL recipient and USDC token account on Solana plus a fresh memo. To pay on this service''s rail: pay with the memo attached (Solana Memo program), then retry with header ''X-Payment-Tx: <transaction signature>'' and query parameter ''toll_memo=<memo>''.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
                legs:
                  type: array
                  description: array of strings (required) - 2-3 distinct live leg codes (nl, ca, us)
                  items:
                    type: string
              required:
              - address
              - legs
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
      security:
      - x402Payment: []
      operationId: postTollAddressBundleValidate
      x-operation-id-source: derived
  /toll/address/legs:
    get:
      tags:
      - Address Verdicts
      summary: 'Address leg catalog: per-leg states and honesty'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      security: []
      operationId: getTollAddressLegs
      x-operation-id-source: derived
  /toll/address/legs/ca/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'Canada leg path: bundle-member only, refuses free'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      security: []
      operationId: postTollAddressLegsCaValidate
      x-operation-id-source: derived
  /toll/address/legs/nz/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'New Zealand leg: catalogued, not yet available'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      security: []
      operationId: postTollAddressLegsNzValidate
      x-operation-id-source: derived
  /toll/address/legs/es/validate:
    post:
      tags:
      - Address Verdicts
      summary: 'Spain leg: catalogued, not yet available'
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      security: []
      operationId: postTollAddressLegsEsValidate
      x-operation-id-source: derived
  /toll/address/bundle/validate/preflight:
    post:
      tags:
      - Address Verdicts
      summary: Free preflight twin of the address bundle op
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
                legs:
                  type: array
                  description: array of strings (required) - 2-3 distinct live leg codes (nl, ca, us)
                  items:
                    type: string
              required:
              - address
              - legs
      security: []
      operationId: postTollAddressBundleValidatePreflight
      x-operation-id-source: derived
  /toll/address/legs/{cc}/validate/preflight:
    post:
      tags:
      - Address Verdicts
      summary: Free preflight twin of an address leg op
      responses:
        '200':
          description: Success. Response shape is documented in the service catalog (GET /health on the service).
      parameters:
      - name: cc
        in: path
        required: true
        schema:
          type: string
        description: Leg code
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: 'object (required) - structured components {unit?: string, street_number: string (required), street_name: string (required), street_type?: string, locality: string (required), state?: string, postcode: string (required)}'
              required:
              - address
      security: []
      operationId: postTollAddressLegsByCcValidatePreflight
      x-operation-id-source: derived
components:
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-Payment-Tx
      description: 'x402 toll payment proof: the Solana transaction signature of a payment carrying the memo from the 402 challenge; send together with ?toll_memo=<memo>. Payment itself is made on-chain in SOL or USDC to the recipient named in the challenge.'