Boltz-2

Overview

Single-chain protein structure prediction from sequence.
Cofolding protein, DNA, RNA, and mixed polymer assemblies.
Protein-small-molecule pose prediction from SMILES or CCD identifiers.
Prepared Boltz YAML runs for templates, constraints, paired MSAs, or advanced schemas.
Batch screening of many YAML or FASTA inputs.

Modes

Mode	Input shape	When to use it
`single_sequence` Single Sequence Default	Uses one selected file/source when file parameters are present.	Generate a Boltz YAML input for one protein chain and predict its structure.
`build_assembly` Build Assembly	No uploaded input is required by the mode itself.	Generate a Boltz YAML input for one or more protein, DNA, or RNA chains, optional residue modifications, an optional small molecule, and affinity output.
`custom_input` Custom Input	Uses one selected file/source when file parameters are present.	Run a supplied Boltz YAML or FASTA file for advanced schemas, constraints, templates, or molecules.
`batch_input` Batch Input	Consumes a folder or output set; useful for batches and pipeline handoffs.	Run all Boltz YAML or FASTA inputs in the selected source.

Canonical Job Configuration

These are the fields exposed by the default job configuration for boltz-2. They are also returned by GET /api/v1/program/params?program=boltz-2 and submitted as the params JSON object to POST /api/v1/job/submit.

Parameter	Type	Modes	What it does
`protein_sequence` Protein Sequence	Sequence	Single Sequence	Single protein chain sequence using standard one-letter amino-acid codes; X is accepted for unknown residues. Required
`protein_chain_id` Protein Chain ID	Text	Single Sequence	Chain identifier used in the generated Boltz YAML. Default: A
`msa_source` Protein MSA Source	Text	Single Sequence	Single Sequence writes msa: empty. Precomputed MSA uses a supplied A3M alignment file. Default: Single Sequence; Options: Single Sequence, Precomputed MSA
`msa_file` Protein MSA File	MSA file	Single Sequence	Choose a precomputed A3M alignment for the single chain. Required; Files: .a3m; Shown when msa_source is Precomputed MSA
`entities` Polymer Chains	Repeatable group	Build Assembly	Add one or more protein, DNA, or RNA chains for cofolding. For dsDNA or paired RNA, add two nucleic-acid chains and enter the second strand as the reverse complement. Build Assembly writes msa: empty for protein chains; use Custom Input for paired MSAs, templates, constraints, symmetry, or larger assemblies. Required; Default: [{"chain_id":"A","cyclic":false,"entity_type":"Protein","modifications":[],"sequence":""}]; Items: 1-12
`entities.entity_type` Type	Text	All modes	Polymer entity type written into the generated Boltz YAML. Default: Protein; Options: Protein, DNA, RNA
`entities.chain_id` Chain ID	Text	All modes	Boltz chain identifier such as A, B, or target_1. Default: A
`entities.sequence` Sequence	Sequence	All modes	Protein amino-acid sequence, DNA sequence, or RNA sequence for this chain. Protein chains may use X for unknown residues. DNA duplexes require separate strand entries, with each strand entered 5-prime to 3-prime. Required
`entities.cyclic` Cyclic	Yes/no	All modes	Mark this polymer chain as cyclic in the generated Boltz YAML. Default: false
`entities.modifications` Modifications	Repeatable group	All modes	Optional per-residue CCD replacements, for example position 2 with CCD MSE. At most 32 item(s)
`entities.modifications.position` Position	Integer	All modes	One-indexed residue position in this chain. Required; Minimum: 1
`entities.modifications.ccd` CCD	Text	All modes	Chemical Component Dictionary code, such as MSE for selenomethionine. Required
`include_ligand` Add Small Molecule	Yes/no	Build Assembly	Add one non-polymer ligand as SMILES or CCD. Protein, DNA, RNA, or peptide binders should be added as polymer chains. Default: false
`ligand_type` Ligand Type	Text	Build Assembly	Use SMILES for custom small molecules or CCD for an existing component code. Default: SMILES; Options: SMILES, CCD; Shown when include_ligand is true
`ligand` Ligand	Ligand text	Build Assembly	SMILES or CCD small molecule. Use polymer chain rows for protein, DNA, RNA, or peptide binders; do not encode polymers as SMILES. Required; Shown when include_ligand is true
`ligand_chain_id` Ligand Chain ID	Text	Build Assembly	Chain identifier for the small molecule in the generated YAML. Default: L; Shown when include_ligand is true
`predict_affinity` Predict Affinity	Yes/no	Build Assembly	Request Boltz-2 small-molecule affinity output. This produces affinity_*.json only for one small-molecule ligand, not polymer binders. Default: false; Shown when include_ligand is true
`boltz_input` Boltz Input	Input file	Custom Input	Choose one Boltz YAML or FASTA file. YAML is preferred upstream; FASTA is deprecated but supported. SubSeq seq JSON from previous pipeline steps is also accepted. Required; Files: .yaml, .yml, .fasta, .fa, .faa, .fas, .seq.json
`physical_refinement` Physical Refinement	Yes/no	All modes	Use Boltz-2 inference-time potentials to improve physical plausibility of predicted poses. Default: true
`sampling_depth` Sampling Depth	Text	All modes	Higher settings spend more runtime on recycles and diffusion samples. Default: Standard; Options: Fast, Standard, Thorough, AF3-like
`output_format` Output Format	Text	All modes	Structure file format written by Boltz. Default: mmCIF; Options: mmCIF, PDB

Advanced configuration fields

Parameter	Type	Modes	What it does
`affinity_mw_correction` Molecular Weight Correction	Yes/no	Build Assembly	Apply Boltz-2's molecular-weight correction to the affinity value head. Default: false; Shown when predict_affinity is true
`write_confidence_matrices` Full PAE/PDE Matrices	Yes/no	All modes	Write full pairwise confidence matrices. This can make outputs much larger. Default: false
`random_seed` Random Seed	Integer	All modes	Set for reproducible sampling; leave blank for a random seed. Range: 1-2147483647

Outputs And Metrics

Ranked mmCIF or PDB structures.
Confidence JSON files and optional PAE/PDE matrices.
Affinity JSON when affinity is requested for a supported small-molecule system.
confidence_score is the main ranking score; higher is better.
pTM estimates global complex topology confidence; ipTM focuses on interfaces.
complex_plddt and complex_iplddt summarize local and interface local confidence.
complex_pde and complex_ipde are predicted distance errors in angstroms; lower is better.
affinity_probability_binary is a 0-1 predicted binder probability. affinity_pred_value is log10(IC50 in micromolar), so lower means stronger predicted binding.

Common Examples

Single protein: Single Sequence, paste sequence, keep physical refinement on and Standard sampling.
Protein-ligand pose plus affinity: Build Assembly, add protein chain A, add ligand L as SMILES or CCD, enable Predict Affinity.
Advanced constrained prediction: Custom Input with YAML containing templates, constraints, paired MSAs, or covalent definitions.
Screening set: Batch Input with one prepared YAML or FASTA per target or candidate.

Example API params

{
  "mode": "build_assembly",
  "entities": [
    {
      "entity_type": "Protein",
      "chain_id": "A",
      "sequence": "MKTAYIAKQRQISFVKSHFSRQDILDLI",
      "cyclic": false,
      "modifications": []
    }
  ],
  "include_ligand": true,
  "ligand_type": "SMILES",
  "ligand": "CCO",
  "predict_affinity": true
}

Caveats

Affinity prediction is intended for one small molecule against protein targets; do not interpret it for polymer binders or missing biological partners.
Single-sequence protein inputs are convenient but can be less accurate than predictions with informative MSAs.
Treat affinity and confidence values as computational prioritization, not measured IC50, Kd, activity, or validation.

Advanced Submit

Advanced submit is still available for direct program arguments through POST /api/v1/job/submit-advanced. Prefer canonical configuration unless you need exact low-level arguments or are reproducing a known command line.

Advanced submit passes direct boltz predict inputs and options. Use it for full YAML control, paired MSAs, templates, constraints, symmetry, or custom molecule definitions.
Prefer mmCIF unless a downstream tool specifically requires PDB.

curl -X POST https://subseq.bio/api/v1/job/submit \
  -H "Authorization: Bearer <api_key>" \
  -F program=boltz-2 \
  -F 'params={"mode":"build_assembly","entities":[{"entity_type":"Protein","chain_id":"A","sequence":"MKTAYIAKQRQISFVKSHFSRQDILDLI","cyclic":false,"modifications":[]}],"include_ligand":true,"ligand_type":"SMILES","ligand":"CCO","predict_affinity":true}'