> For the complete documentation index, see [llms.txt](https://docs.bloxchain.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxchain.app/platform-bloxchain.app/use-cases/external-calls.md).

# External protocol calls

**Audience:** Admin · **Time:** \~90 min (testnet)

Call **third-party contracts** (DEX routers, bridges, composers) through guarded execution — only **whitelisted targets** per function selector.

## What you build

| Piece               | Recommendation                                          |
| ------------------- | ------------------------------------------------------- |
| **Operation**       | Guarded `execute(bytes)` (or your integration selector) |
| **Roles**           | `Integration Signer`, **Broadcaster** (protected)       |
| **Workflow**        | Meta request + approve                                  |
| **Allowlist**       | Every router, pool, bridge, and proxy the call touches  |
| **Execution ports** | Review handler graph if multi-step                      |

***

## Prerequisites

* Account workspace + integration addresses from your protocol (router, factory, etc.).
* **Broadcaster** wallet funded for gas.

***

## Step 1 — Security baseline

**Deployment → Security** ([Security settings](/platform-bloxchain.app/overview-1/security-settings.md))

| Setting         | Recommendation                                                            |
| --------------- | ------------------------------------------------------------------------- |
| **Broadcaster** | **Required** — wallet that **Finalize approved request** uses for meta-tx |
| **Owner**       | Integration admin                                                         |
| **Recovery**    | Document before mainnet — [Recovery](/platform-bloxchain.app/recovery.md) |

Meta-transaction path: signer approves off-chain; broadcaster submits on-chain ([How this works](/introduction/operational-model.md)).

***

## Step 2 — Register external execute operation

**Deployment → Operations → Register** ([Operations](/platform-bloxchain.app/overview-1/operations.md))

| Field                 | Value                      |
| --------------------- | -------------------------- |
| Operation name        | `External Execute`         |
| Function signature    | `execute(bytes)`           |
| Workflow capabilities | **Meta request + approve** |

**Sign** → **Execute**.

Use the exact signature your GuardController integration exposes if it differs.

***

## Step 3 — Review execution ports (if shown)

**Deployment → Operations** → select **External Execute** → review workflow / handler diagram ([Execution ports](/platform-bloxchain.app/overview-1/execution-ports.md)).

* Confirm handler selectors match your integration.
* Multi-step flows must have every step registered and permitted.

***

## Step 4 — Create roles

**Deployment → Roles** ([Roles & members](/platform-bloxchain.app/overview-1/roles-and-members.md))

| Role / identity      | Purpose                                                                         |
| -------------------- | ------------------------------------------------------------------------------- |
| `Integration Signer` | Human or service wallet — signs approvals                                       |
| **Broadcaster**      | Protected role — on-chain finalize (set under Security, not a custom role name) |
| Owner                | Admin config only                                                               |

Assign the integration team wallet to `Integration Signer`.

***

## Step 5 — Grant permissions

For **External Execute** ([Permissions](/platform-bloxchain.app/overview-1/permissions.md)):

| Role / wallet      | Pending Request | Sign and approve request | Finalize approved request |
| ------------------ | :-------------: | :----------------------: | :-----------------------: |
| Integration Signer |        ✓        |             ✓            |             —             |
| Broadcaster        |        —        |             —            |             ✓             |

Separation: signer must not be the only party that can both request and finalize without policy review.

***

## Step 6 — Allowlists (critical)

**Allowlists** ([Allowlists](/platform-bloxchain.app/overview-1/allowlists.md)) → **Contract targets**

For selector **External Execute**, whitelist **every** address the composed transaction calls:

| Target type | Example                                  |
| ----------- | ---------------------------------------- |
| Router      | Uniswap / aggregator router              |
| Pool / pair | Liquidity pool contract                  |
| Bridge      | L1/L2 bridge proxy                       |
| User proxy  | Composer or account abstraction proxy    |
| Your dapp   | App contract invoked by `execute(bytes)` |

**Empty whitelist = deny all** external targets for that selector.

Add targets before testing — failed allowlist checks revert on-chain.

***

## Step 7 — Connect your application

1. Copy **execution selector** and **target addresses** from your integration ([Connect your application](/platform-bloxchain.app/overview-1/connect-your-application.md)).
2. Point backend / agent SDK at **Account workspace** `contractAddress`.
3. Signer wallet holds sign permissions only; broadcaster wallet configured under Security.
4. See [SDK core patterns](/developers/sdk-core-patterns.md) for meta-tx build/sign flow.

***

## Step 8 — Test

1. **Integration Signer** → [Submit request](/platform-bloxchain.app/overview/submit-request.md) with a **small** call to an allowlisted router.
2. Sign approval → **Broadcaster** finalizes (or approver if you collapsed finalize).
3. Confirm success in [History](/platform-bloxchain.app/overview/history.md).
4. Retry same call to a **non-allowlisted** address — expect revert.

***

## Checklist

* [ ] `execute(bytes)` (or integration selector) registered
* [ ] Broadcaster set and funded
* [ ] All call targets allowlisted
* [ ] Signer cannot unilaterally finalize without policy
* [ ] Disallowed target fails predictably on testnet

## Protocol

[Guard controller](/protocol/guard-controller.md) · [Meta-transactions](/protocol/meta-transactions.md)

## Developers

[SDK core patterns](/developers/sdk-core-patterns.md) · [Integration surfaces](/developers/integration-surfaces.md)

## Related

* [Use cases](/platform-bloxchain.app/use-cases.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bloxchain.app/platform-bloxchain.app/use-cases/external-calls.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.