Developer Cookbook

The below examples assume you're running a Python agent alongside a Django server for the agent developer's backend.

API Key Setup

# The API can be initialized within the agent and/or within the backend
from agent_protocol import AgentProtocol

ap = AgentProtocol(api_key="YOUR_API_KEY")

Initializing an Agent

Agents can be initialized anywhere. This will create a unique agent ID.

new_agent = ap.init_agent(
    name="MyAgent",
    user_agent_protocol_id="userID"
    description="An assistant agent"
)

print(f"New agent created with ID: {new_agent.id}")

Linking a User's Plaid Account

Agent Developer Django Server:

Here you must pass in the user's unique Agent Protocol ID. The callback URL will receive a user-specific key for their Plaid authorization.

@api_view(['GET'])
def plaid_redirect(request):
    user_oauth_link = ap.init_plaid_oauth(user_ap_id, callback_url)
    redirect(user_oauth_link)


@api_view(['POST'])
def plaid_callback(request):
    user_plaid_key = request.POST.get("user_plaid_key")
    # Store the above key somewhere safe
    ...

Creating & Funding a Virtual Fiat Card

Agent Developer Django Server:

@api_view(['POST'])
def create_fiat_card(request):
    user_ap_id = ...
    user_plaid_key = ...

    amount_to_transfer = ...  # Extract the deposit from the request
    permissions = ...  # Permissions specified in the request like daily limits
    card = ap.create_fiat_card(user_ap_id, **permissions)
    ap.fund_fiat(card.id, user_plaid_key, amount_to_transfer)
    # Store the card ID somewhere or immediately assign it to an agent
    ap.assign_card(card.id, agent_id)

Creating & Funding a Crypto Keypair

Agent code:

# The agent should do this immediately on instantiation if it intends on using crypto
def create_keypair():
    # The agent creates its own private keypair
    pubkey, private_key = ap.gen_keypair(blockchain="solana")
    # The private_key should be stored securely somewhere
    # Agent-developer defined function to invoke `create_crypto_card` below
    result = await call_create_crypto_card(
        pubkey,
        blockchain="solana",
        permissions={...},
        funding_type=...
    )
    return result

Agent Developer Django Server:

@api_view(['POST'])
def create_crypto_card(request):
    # Extract the agent-generated pubkey from the request
    pub_key = request.POST.get("pubkey")
    permissions = ...  # Spend limits, etc.
    card = ap.authorize_keypair(
        agent_id,
        blockchain="solana",
        **permissions
    )
    if request.POST.get("funding_type") == "fiat":
        ap.fund_fiat(card.id, user_plaid_key, amount_to_transfer)
    elif request.POST.get("funding_type") == "crypto":
        # Prompt the user to fund the specified pub_key
        authorized_pubkey = ap.fund_crypto(card.id)
        ...
    else:
        raise Exception
    ap.assign_card(card.id, agent_id)
    return 200

Handing Transaction Failures

Agent Developer Django Server:

@api_view(['POST'])
def transaction_failed_callback(request):
    # This endpoint should be shared with Agent Protocol when transactions fail
    failure_type = request.POST.get("failure_type")
    if failure_type == ap.errors.SPEND_LIMIT_EXCEEDED:
        # Agent developer asks the user if they'd like to approve/manually handle
        user_manually_approved = ...
        if user_manually_approved:
            ap.increase_spend_limit(
                request.POST.get("card_id"),
                request.POST.get("recommended_spend_limit")
            )
        else:
            # If you don't respond within a specified time period, then then the txn is considered failed
            pass
    elif failure_type = ap.errors.RESTRICTED_VENDOR:
        ...
    elif failure_type = ap.errors.OUT_OF_FUNDS:
    	...