Python SDKNew

The first-party Ramp Python SDK provides typed sync and async clients generated from Ramp's reviewed API contracts. The initial public preview covers selected Agent Tools, Agent Cards, Standalone Agent discovery, and Agent Wallet policy operations.

The SDK is in public preview and is not yet published to PyPI. Install the preview directly from the public repository.

Install

The SDK supports Python 3.11 and newer. Its built-in HTTPX runtime handles token acquisition and authenticated requests:

python -m pip install \
  "ramp-python @ git+https://github.com/ramp-public/ramp-python.git@4bd7c2240546ef94d7ec7a9aa48c7ebf91a61074"

Authenticate a Standalone Agent

Agent execution uses a Ramp Standalone Agent identity with a dedicated OAuth client. Export that client's ID and secret for the environment where it was created. Keep both values in a secret manager; do not put them in source code or logs.

export RAMP_CLIENT_ID="your-standalone-agent-client-id"
export RAMP_CLIENT_SECRET="your-standalone-agent-client-secret"

The SDK exchanges these credentials with the OAuth 2.0 client-credentials grant and reuses the resulting bearer token until shortly before it expires. Core binds that token to the Standalone Agent identity and its configured scopes. This is not the interactive Developer API authorization-code flow and does not require a human consent redirect.

The credential's identity is determined by Ramp, not by the SDK. A generic Developer API client ID and secret produce a business-scoped token; passing them to this client does not turn that application into a Standalone Agent. Business control-plane operations may require that business-scoped identity even when execution operations use a Standalone Agent token. See Ramp API authorization for OAuth scopes and token lifecycle details.

RAMP_AGENT_WALLET_API_KEY belongs to an earlier Agent Wallet authentication flow. The Python SDK intentionally does not read or transmit it. New Standalone Agent integrations should use the client ID and client secret.

Configure the client

Ramp.from_env() requires both credential variables and defaults to the sandbox environment. Credentials and tokens are environment-specific; select production explicitly for a production identity:

from ramp.client import Ramp
 
 
client = Ramp.from_env(environment="production")

Create one client per application lifecycle so connections and access tokens are reused, then close it when the application shuts down. Callers that already manage token acquisition can instead pass access_token=... directly.

List eligible Agent Card funds

agent_cards.list_funds is a read-only Standalone Agent operation. It discovers the funds eligible for a later Agent Card payment-token request without returning card credentials:

funds = client.agent_tools.agent_cards.list_funds(
    rationale="Find funds eligible for an approved Agent Card payment",
)
 
for fund in funds["funds"]:
    print(fund)

The same Standalone Agent bearer token authenticates supported Agent Tools and Agent Wallet execution requests. Creating a payment token is a separate, sensitive write; do not print or persist its credential material.

Find bills that need review

bills.list is read-only and requires the bills:read scope. It uses cursor pagination in the request body.

cursor: str | None = None
max_pages = 5
 
for _ in range(max_pages):
    page = client.agent_tools.bills.list(
        query="Acme",
        include_paid=False,
        limit=50,
        page_cursor=cursor,
        rationale="Find unpaid Acme bills for the weekly AP review",
    )
 
    for bill in page["bills"]:
        print(bill)
 
    cursor = page.get("next_page_cursor")
    if not cursor:
        break
else:
    print(f"Stopped after the configured {max_pages}-page budget")

The preview returns response mappings. Generated response models will replace those mappings as the SDK expands.

Attach a quote to a procurement request

procurement_requests.upload_file requires the spend_requests:write scope and the developer_api_procurement_request_agent_tools_enabled gate. The operation is currently available to the CLI platform contract.

from pathlib import Path
from uuid import UUID
 
 
result = client.agent_tools.procurement_requests.upload_file(
    spend_request_uuid=UUID("00000000-0000-0000-0000-000000000001"),
    field_id="supporting-document",
    file=Path("vendor-quote.pdf"),
    rationale="Attach the selected vendor quote to the request draft",
)
 
print(result["file_uuid"])

Replace the example UUID and field ID with values from the procurement request you are updating. Runtime availability still depends on the authenticated identity's permissions and the business's enabled features.

Issue one-off funds

funds.create is destructive: it creates virtual-card-only spend allocations outside approval flows. It requires funds:write, the agent_fund_creation gate, and the acting user's permission to issue spend without approval. Require an explicit human confirmation in your application before calling it.

def get_admin_confirmation_from_your_application() -> bool:
    """Integrate this with your real human approval workflow."""
    raise NotImplementedError("Connect an admin approval workflow first")
 
 
confirmed_by_admin = get_admin_confirmation_from_your_application()
 
if not confirmed_by_admin:
    raise RuntimeError("An admin must approve fund issuance")
 
result = client.agent_tools.funds.create(
    amount="500.00",
    display_name="Customer onsite travel",
    interval="TOTAL",
    user_ids=["00000000-0000-0000-0000-000000000002"],
    rationale="Issue the approved travel budget for the customer onsite",
)
 
print(result["spend_allocation_ids"])

Replace the example user ID with the intended recipient. Do not automatically retry this call after a timeout or ambiguous network failure; first reconcile whether Ramp created the allocation.

Clean up

Close the client when your application shuts down:

client.close()

For asynchronous applications, AsyncRamp.from_env() uses the same credentials and resource tree. Use it as an async context manager so its owned HTTP client is closed:

from ramp.client import AsyncRamp
 
 
async with AsyncRamp.from_env(environment="production") as client:
    funds = await client.agent_tools.agent_cards.list_funds(
        rationale="Find funds eligible for an approved Agent Card payment",
    )