BYOK Provider Setup

Oris uses a Bring Your Own Keys (BYOK) architecture. You maintain your own accounts with payment infrastructure providers. You register your API credentials with Oris through envelope encryption. This guide walks through connecting each supported provider.

Your credentials are protected by envelope encryption. Each developer receives a unique AES-256-GCM data key. That key is encrypted by HashiCorp Vault Transit. Plaintext credentials never persist in storage or in memory beyond a single request. See the Architecture page for full details.

Supported Providers

ProviderPurposeRequired Keys
PimlicoERC-4337 bundler (gasless payments on EVM chains)api_key
CircleUSDC minting, programmable walletsapi_key, master_wallet_id
TurnkeyInstitutional key managementorg_id, api_public_key, api_private_key
FireblocksEnterprise vault and custodyapi_key, api_secret, vault_id

Pimlico (Gasless EVM Payments)

Get Your Pimlico API Key

  1. Create a free account at pimlico.io.
  2. Open the Dashboard and go to Settings. Create a new API key.
  3. Select the chains you want to support (Base, Polygon, Arbitrum, and others).
  4. Copy the API key. It starts with pm_live_ or pm_test_.

Register with Oris

pimlico_setup.py
client.provider_keys.save( provider="pimlico", credentials={"api_key": "pm_live_abc123..."} )

Verify

status = client.provider_keys.status() assert status["pimlico"]["configured"] == True
Free tier available. Pimlico's free tier includes 100 sponsored UserOperations per month. This is sufficient for development and testing.

Circle (USDC and Fiat)

Get Your Circle Credentials

  1. Create a developer account at circle.com/developers.
  2. Generate an API key in the Developer Console.
  3. Create a Master Wallet for USDC operations.
  4. Note the Master Wallet ID from the wallet details page.

Register with Oris

circle_setup.py
client.provider_keys.save( provider="circle", credentials={ "api_key": "CIRCLE_API_KEY", "master_wallet_id": "MASTER_WALLET_ID" } )

Turnkey (Institutional Key Management)

Get Your Turnkey Credentials

  1. Sign up at turnkey.com.
  2. Create an organization. Note the Organization ID.
  3. Generate an API key pair (public key and private key) in the Organization Settings.

Register with Oris

turnkey_setup.py
client.provider_keys.save( provider="turnkey", credentials={ "org_id": "YOUR_ORG_ID", "api_public_key": "YOUR_PUBLIC_KEY", "api_private_key": "YOUR_PRIVATE_KEY" } )

Fireblocks (Enterprise Custody)

Get Your Fireblocks Credentials

  1. Log in to the Fireblocks Console.
  2. Go to Settings, then API Users. Create a new API user.
  3. Download the API secret (RSA private key).
  4. Note the API key and the Vault Account ID.

Register with Oris

fireblocks_setup.py
client.provider_keys.save( provider="fireblocks", credentials={ "api_key": "YOUR_API_KEY", "api_secret": "YOUR_RSA_PRIVATE_KEY", "vault_id": "YOUR_VAULT_ID" } )

Managing Provider Keys

Check Connection Status

The status endpoint returns connection state for all providers. It never returns plaintext key values.

status = client.provider_keys.status() print(status) # { # "pimlico": {"configured": true, "updated_at": "2026-03-24T10:30:00Z"}, # "circle": {"configured": true, "updated_at": "2026-03-24T10:31:00Z"}, # "turnkey": {"configured": false, "updated_at": null}, # "fireblocks": {"configured": false, "updated_at": null} # }

Rotate a Key

Call save() again with the same provider name. The new credentials replace the previous ones.

# Save the new key. It replaces the previous one. client.provider_keys.save( provider="pimlico", credentials={"api_key": "pm_live_new_key..."} )

Remove a Provider

Deleting a provider removes the encrypted credentials from Vault. Any agents using that provider will fail payment execution until you register a replacement.

client.provider_keys.delete(provider="pimlico")

Security Notes

Next Steps