Integrate with FastAPI

[fubuloubu]

Describe

It'd be really nice to have an easy way to integrate Ape with a framework like FastAPI, so that certain network requests could be handled within a specific network context (including request body validation)

Specification

Not sure how this would work in practice, but something like:

@app.post("/{ecosystem}/{network}/...")
@ape.networks.wrap_context()
def send_transaction(body: ParsedWithApeConverts):
    tx = body.target.method(*body.args, sender=settings.sender)
    return tx.hash

Dependencies

No response

[linear]

APE-2048

[ChickenBenny]

Hi @fubuloubu, I would love to pick up this issue!

Reading your description, I noticed you mentioned integrating with a framework "like" FastAPI. This brings up an important architectural question before I start drafting the code:

1. Framework-Agnostic vs. FastAPI-Specific Context:
   Since you proposed a @ape.networks.wrap_context() decorator, I assume the goal is to keep this utility framework-agnostic (so it works with Flask, Starlette, etc.), rather than using FastAPI's specific Depends() injection system. Is my understanding correct? If so, I'll focus on building a robust async/sync decorator.

2. Pydantic Type Validation (ParsedWithApeConverts):
   FastAPI heavily relies on Pydantic. To allow request bodies to automatically parse Ape types (like AddressType), we'll need to implement __get_pydantic_core_schema__ for Ape's custom types so Pydantic v2 knows how to use ape.convert(). Do you agree with this direction?

Let me know your thoughts, and I can start working on a Draft PR!

[fubuloubu]

Hi @fubuloubu, I would love to pick up this issue!

Awesome, thanks for giving it a shot!

Reading your description, I noticed you mentioned integrating with a framework "like" FastAPI. This brings up an important architectural question before I start drafting the code:

1. Framework-Agnostic vs. FastAPI-Specific Context:
   Since you proposed a @ape.networks.wrap_context() decorator, I assume the goal is to keep this utility framework-agnostic (so it works with Flask, Starlette, etc.), rather than using FastAPI's specific Depends() injection system. Is my understanding correct? If so, I'll focus on building a robust async/sync decorator.

FastAPI is definitely the best one to support first. I use it frequently for prototyping systems integrations with Ape, a good example being the service component in https://github.com/ApeWorX/stablecoin. But I suppose to be future proof, it would be good to add it to an "external integrations" module, perhaps from ape.ext.fastapi import network_context which would be a purpose-built decorator for use with FastAPI, and thus could take advantage of its features (such as Query dependency resolution)

The most important thing is that the integration should feel seamless and work well, and specifically since services are designed to be multi-network it is important that routes can be executed in different contexts. Here's how a vanilla integration with FastAPI might look as an example (a token faucet):

from ape import convert, networks
from ape.types import AddressType
from ape_tokens import Token


@app.post("/faucet/{token}")
def send_erc20_token(
    token: str,
    # body params take advantage of Ape's conversion system in `token.transfer` below
    receiver: str | AddressType,
    amount: str | int,
    # need these other know which network to send on
    ecosystem: str = Query(),
    network: str = Query(),
) -> str: 
    with networks[ecosystem][network].use_default_provider():
        # do things in network context
        token = Token.at(convert(token, AddressType))
        tx = token.transfer(receiver, amount, sender=...)
        return tx.txn_hash

So a nice integration might look like

from ape import convert
from ape.ext.fastapi import network_context
from ape.types import AddressType
from ape_tokens import Token


@app.post("/faucet/{token}")
@network_context()
def send_erc20_token(
    token: str,
    # body params take advantage of Ape's conversion system in `token.transfer` below
    receiver: str | AddressType,
    amount: str | int,
) -> str: 
    # automatically has network context
    token = Token.at(convert(token, AddressType))
    tx = token.transfer(receiver, amount, sender=...)
    return tx.txn_hash

And we could explore further things for conversions, etc.

---

Note that we actually don't support async network context yet, so only synchronous routes would be possible at this time.

2. Pydantic Type Validation (ParsedWithApeConverts):
   FastAPI heavily relies on Pydantic. To allow request bodies to automatically parse Ape types (like AddressType), we'll need to implement __get_pydantic_core_schema__ for Ape's custom types so Pydantic v2 knows how to use ape.convert(). Do you agree with this direction?

Some of this has already been done with eth-pydantic-types (another repo of ours), although it is not integrated with ape's conversion system (e.g. vitalik.eth resolving to address, "100 USDC" resolving to integer value). Conversions could be considered with this implementation, but note that both of those require external integrations or even a network connection to function so perhaps it's best just to ignore conversions for now.

[ChickenBenny]

Hi @fubuloubu, this is super helpful!

Based on your guidance, here is my execution plan:

1. Create ape/ext/fastapi.py and implement the @network_context decorator.
2. The decorator will extract ecosystem and network from the request (e.g., via path or query params) and automatically enter the context using networks[ecosystem][network].use_default_provider().
3. Support only synchronous routes for now, as async context is not yet supported.
4. Add fastapi as an optional dependency in the project setup.
5. Skip the custom Pydantic type validation for ape.convert() in this PR, as you suggested.

Please let me know if this approach sounds solid, and I'll start putting together a Draft PR!

[ChickenBenny]

Hi @fubuloubu, I've submitted a PR for this issue: #2762

I implemented ape.ext.fastapi with a network_context() decorator as discussed. Also, I'd love to keep contributing to Ape — are there other good issues I could pick up, especially around integrations or the network/provider layer? I'm also happy to extend ape.ext to support other frameworks like Flask or Django if that's something you'd like to see. Just let me know!

[fubuloubu]

Hi @fubuloubu, I've submitted a PR for this issue: #2762

I implemented ape.ext.fastapi with a network_context() decorator as discussed. Also, I'd love to keep contributing to Ape — are there other good issues I could pick up, especially around integrations or the network/provider layer? I'm also happy to extend ape.ext to support other frameworks like Flask or Django if that's something you'd like to see. Just let me know!

I think a fun way to take what you just built and apply it is to create an example service using it. My go to has been making a faucet (see https://github.com/ApeWorX/faucet, which is in desperate need of some love), or you can propose an update to that stablecoin service I mentioned above