visa-check

Whether a passport holder can enter a destination country: visa-free, visa on arrival, e-visa, eTA, or visa required — with allowed stay, official application portal, extended rules (passport validity, onward ticket, yellow fever, transit-without-visa) and source citations. Free tier: rate limited per caller (see /auth.md to register for a larger quota, or use the x402-paid HTTP API for unlimited access).

{
  "type": "object",
  "properties": {
    "passport": {
      "type": "string",
      "description": "Passport country, ISO 3166-1 alpha-3 (e.g. NLD)"
    },
    "destination": {
      "type": "string",
      "description": "Destination country, ISO 3166-1 alpha-3 (e.g. JPN)"
    },
    "transit": {
      "type": "string",
      "description": "Optional transit country, ISO 3166-1 alpha-3"
    },
    "purpose": {
      "type": "string",
      "description": "Travel purpose (default: tourism)"
    },
    "residence_permits_of": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issuers of residence permits held (ISO3 or SCHENGEN/EU/GCC)"
    },
    "visas_of": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issuers of visas held (ISO3 or SCHENGEN/EU/GCC)"
    }
  },
  "required": [
    "passport",
    "destination"
  ]
}

{
  "type": "object",
  "properties": {
    "requirement": {
      "type": "string",
      "description": "visa_free | visa_on_arrival | e_visa | eta | visa_required | no_admission | unknown | needs_review"
    },
    "requirement_label": {
      "type": "string",
      "description": "Human-readable verdict"
    },
    "allowed_stay_days": {
      "type": [
        "number",
        "null"
      ],
      "description": "Maximum stay in days when the verdict grants one"
    },
    "apply": {
      "type": [
        "object",
        "null"
      ],
      "description": "Official government application/information portal when action is required",
      "properties": {
        "url": {
          "type": "string",
          "description": "Official portal URL"
        },
        "kind": {
          "type": "string",
          "description": "evisa | eta | visa_info"
        },
        "source": {
          "type": "object",
          "description": "Official-source citation for the field it accompanies",
          "properties": {
            "name": {
              "type": "string",
              "description": "Official authority name"
            },
            "url": {
              "type": "string",
              "description": "Official page the rule was verified against"
            },
            "retrieved_at": {
              "type": "string",
              "description": "YYYY-MM-DD the source was last retrieved"
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "entry_rules": {
      "type": "object",
      "description": "Destination entry rules: passport_validity, blank_pages, onward_ticket, yellow_fever, other_health, twov (transit-without-visa), residence_permit_exemptions, official_links, purpose_scope — each non-null field cites its official source {name, url, retrieved_at}, plus last_verified and coverage (extended|basic).",
      "additionalProperties": true
    },
    "verdict_verification": {
      "type": "object",
      "description": "Provenance of the visa verdict itself — always derives from an aggregated secondary matrix (status secondary_source_only or needs_review), never claimed officially verified",
      "additionalProperties": true
    },
    "entry_rules_verification": {
      "type": "object",
      "description": "Provenance of the curated entry-rules layer: verified_official_sources | stale | not_curated | needs_review, with last_verified and staleness_days",
      "additionalProperties": true
    },
    "defaults_applied": {
      "type": "array",
      "description": "Assumptions applied to answer (e.g. purpose=tourism, ordinary passport)",
      "items": {
        "type": "string"
      }
    },
    "dataset_version": {
      "type": "string",
      "description": "Base-matrix revision (YYYY-MM-DD)"
    },
    "request_id": {
      "type": "string",
      "description": "Unique id for reproducibility"
    }
  },
  "description": "Visa verdict with entry rules and split provenance. Unknown or conflicting data is served as requirement 'unknown'/'needs_review' with action check_official_authority — never guessed.",
  "additionalProperties": true
}

Premium evaluation of a whole trip in one call: multiple passports (best passport per leg), documents held, multi-leg itineraries with transit legs, dates and purpose — with structured why[] explanations, conditions[], and verification states per decision. PAID endpoint: the call returns HTTP 402 x402 payment instructions unless the request carries an x402 payment header; any x402-capable client settles in USDC on Base and retries.

{
  "type": "object",
  "properties": {
    "traveler": {
      "type": "object",
      "description": "The traveler's documents",
      "properties": {
        "passports": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "ISO3, 1-4 passports"
        },
        "residence_permits_of": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Issuers of residence permits held (ISO3 or SCHENGEN/EU/GCC)"
        },
        "visas_of": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Issuers of valid visas held (ISO3 or SCHENGEN/EU/GCC)"
        }
      },
      "required": [
        "passports"
      ]
    },
    "trip": {
      "type": "object",
      "description": "The itinerary to evaluate, in travel order",
      "properties": {
        "purpose": {
          "type": "string",
          "description": "Trip-wide travel purpose (default: tourism); per-leg purpose overrides"
        },
        "legs": {
          "type": "array",
          "description": "Trip legs in order, up to 10",
          "items": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string",
                "description": "Leg country, ISO 3166-1 alpha-3"
              },
              "role": {
                "type": "string",
                "enum": [
                  "entry",
                  "transit"
                ],
                "description": "entry = enter the country; transit = pass through in transit"
              },
              "arrival_date": {
                "type": "string",
                "description": "YYYY-MM-DD; enables stay-duration and validity-window checks"
              },
              "departure_date": {
                "type": "string",
                "description": "YYYY-MM-DD; enables stay-duration and validity-window checks"
              },
              "purpose": {
                "type": "string",
                "description": "Overrides the trip purpose for this leg"
              }
            },
            "required": [
              "country"
            ]
          }
        }
      },
      "required": [
        "legs"
      ]
    }
  },
  "required": [
    "traveler",
    "trip"
  ]
}

{
  "type": "object",
  "properties": {
    "legs": {
      "type": "array",
      "description": "One decision per leg: requirement, best_option (which held passport/document wins), why[] explanations with sources, conditions[] (validity, onward ticket, yellow fever, stay-duration fit), and a verification state",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "trip_summary": {
      "type": "object",
      "description": "Aggregate outcome",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Present on the unpaid path: 'payment_required'"
    },
    "x402_requirements": {
      "type": [
        "object",
        "null"
      ],
      "description": "x402 v2 payment requirements (decoded from the PAYMENT-REQUIRED header): pay in USDC on Base and retry the same call",
      "additionalProperties": true
    }
  },
  "description": "Per-leg decisions with explanations, or — when the request carried no x402 payment — the machine-readable payment instructions to settle and retry.",
  "additionalProperties": true
}

Coverage and freshness of the underlying visa-requirements dataset, plus endpoints and x402 pricing for the unlimited paid tier.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "retrieved_at": {
          "type": "string",
          "description": "Base-matrix revision (YYYY-MM-DD)"
        }
      },
      "additionalProperties": true
    },
    "free_endpoint": {
      "type": "object",
      "description": "The free rate-limited check endpoint",
      "properties": {
        "url": {
          "type": "string"
        },
        "price": {
          "type": "string"
        },
        "limit": {
          "type": "string",
          "description": "Free-tier quota"
        }
      },
      "additionalProperties": true
    },
    "paid_endpoints": {
      "type": "object",
      "description": "x402 pay-per-request endpoints (USDC on Base, no account)",
      "properties": {
        "check": {
          "type": "object",
          "additionalProperties": true
        },
        "matrix": {
          "type": "object",
          "additionalProperties": true
        },
        "evaluate": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "transparency": {
      "type": "string",
      "description": "Data-quality metrics URL"
    },
    "docs": {
      "type": "string",
      "description": "LLM-facing documentation URL"
    }
  },
  "description": "Dataset revision plus the free and x402-paid endpoints with current prices",
  "additionalProperties": true
}