> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Submit smart contracts for decoding on Dune programmatically, and track the status of your submissions. This is the API equivalent of the [contract submission form](https://dune.com/contracts/new), built for teams that maintain many contracts or refresh ABIs on every deploy.

## Use Cases

* **Bulk submission**: Submit up to 100 contracts in one request, for example every contract of a protocol on a new chain.
* **ABI refresh**: Resubmit an updated ABI after an upgrade instead of filling in the form again.
* **CI integration**: Submit from a deploy pipeline and poll for the result, using idempotency keys so retries are safe.
* **Status tracking**: List your submissions and filter by chain, project, contract, or status.

<CardGroup cols={2}>
  <Card title="Submit Contracts for Decoding" icon="file-import" href="/api-reference/contracts/endpoint/decode">
    Submit a batch of contracts with their ABIs and get a per-item result.
  </Card>

  <Card title="List Contract Submissions" icon="list" href="/api-reference/contracts/endpoint/list">
    Track the status of the submissions made by your account.
  </Card>
</CardGroup>

<br />

## How Decoding Submissions Work

1. You submit a contract with its ABI. Each item in the batch is validated and stored independently, so one bad item does not fail the others.
2. Accepted items start as `pending`. Dune's decoding pipeline picks them up within a minute and moves them to `approved`, `rejected`, or `needs_manual_review`.
3. Approved submissions are processed and decoded tables appear under `<project_name>_<blockchain>.<contract_name>_evt_*` and `_call_*` in the Data Explorer, after which the status becomes `processed`.

<Note>
  **Some submissions always go to manual review.** ABI upgrades (`submission_type: "upgrade"`), renames, deletions, and submissions to protected namespaces are queued for a Dune team member to review rather than processed automatically. They will show `needs_manual_review` until then.
</Note>

## Requirements

* **Attributed to you.** Submissions are attributed to the Dune user who created the API key, the same way the form attributes them to the logged-in user. For a team's key that user must still be a member of the team.
* **Read/Write scope** to submit, **Read** scope to list.
* **Paid plan for advanced submissions.** Free plans can submit new contracts for one blockchain per request. Batches spanning multiple blockchains, and resubmissions (`upgrade`, `rename`, `delete`, `other`), require a paid plan: the team's plan for a team API key.

Submissions made through the API appear alongside your form submissions in the [Dune UI](https://dune.com/contracts/new), and the same [contract submission guidance](/web-app/decoding/short-guide-contract-submission) applies.