Skip to main content
API docs by Redocly

SafeBank Infrastructure API (1.0.0)

Download OpenAPI specification:Download

Issuing, settlement, refunds, and on-ramp infrastructure for partner platforms.

cards

Issue a card

Creates a virtual card for the given cardholder. Behavior depends on the ISSUING_PROVIDER config: Stripe issues a Stripe Issuing card; Bridge creates a Bridge card account funded by the supplied crypto account.

Request Body schema: application/json
required
cardholderId
required
string

Cardholder UUID returned from POST /v1/cardholders.

chain
string
Enum: "solana" "world_chain" "base"

Bridge only — blockchain for the card account funding source.

cryptoAccountAddress
string

Bridge only — crypto account address that funds card draws.

cryptoAccountType
string
Enum: "standard" "bridge_wallet"

Bridge only — crypto account type. Defaults to standard.

Responses

Request samples

Content type
application/json
{
  • "cardholderId": "550e8400-e29b-41d4-a716-446655440000",
  • "chain": "solana",
  • "cryptoAccountAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  • "cryptoAccountType": "standard"
}

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "stripeCardId": "ic_1NXxxx",
  • "bridgeCardAccountId": "card_acc_abc123",
  • "last4": "4242"
}

Issue Stripe ephemeral key for wallet push-provisioning

Returns a Stripe Issuing ephemeral key suitable for Apple Pay In-App Provisioning, Google Pay JS push tokenization, or client-side Stripe.js PAN display. Stripe-only: rejects with 400 when ISSUING_PROVIDER=bridge. Tightly rate-limited (5/min/IP) because ephemeral keys are sensitive.

path Parameters
id
required
string
Example: 6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1

SafeBank card UUID

Request Body schema: application/json
required
platform
required
string
Enum: "apple" "google"

Target wallet vendor. apple requires Apple Pay In-App Provisioning fields.

nonce
string

Required for Apple/Google Pay In-App Provisioning push tokenization. Omit for client-side card display via Stripe.js (PAN reveal).

nonceSignature
string

Apple Pay only — base64 signature over nonce produced by PKAddPaymentPassRequest. Required when platform=apple AND nonce is set; omit with nonce for the desktop / dry-run ephemeral-key path.

certificates
Array of strings

Apple Pay only — array of base64 certificates from PKAddPaymentPassRequest. Required when platform=apple AND nonce is set.

Responses

Request samples

Content type
application/json
{
  • "platform": "apple",
  • "nonce": "string",
  • "nonceSignature": "string",
  • "certificates": [
    ]
}

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "stripeCardId": "ic_1NXxxx",
  • "platform": "apple",
  • "ephemeralKey": {
    }
}

Get card spend limits

The configured per-transaction / daily / weekly / monthly caps and MCC rules for a card.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

SafeBank card UUID

Responses

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "perTransactionUsd": "250.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00",
  • "blockedMcc": [ ],
  • "allowedMcc": null
}

Set card spend limits

Sets per-transaction / daily / weekly / monthly USD caps and MCC block/allow rules. Only the fields sent are changed; an explicit null clears a cap or the allowlist. Enforced in real time on every authorization for the card.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

SafeBank card UUID

Request Body schema: application/json
required
perTransactionUsd
object or null

Per-transaction USD cap. null clears it.

dailyUsd
object or null

Rolling 24h USD cap. null clears it.

weeklyUsd
object or null

Rolling ISO-week USD cap. null clears it.

monthlyUsd
object or null

Calendar-month USD cap. null clears it.

blockedMcc
Array of strings

MCCs to decline. Replaces the existing list.

allowedMcc
Array of strings or null

When set, only these MCCs are allowed. null clears the allowlist (allow anything not blocked).

Responses

Request samples

Content type
application/json
{
  • "perTransactionUsd": "250.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00",
  • "blockedMcc": [
    ],
  • "allowedMcc": [
    ]
}

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "perTransactionUsd": "250.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00",
  • "blockedMcc": [ ],
  • "allowedMcc": null
}

Freeze a card

Sets the card inactive at Stripe and in SafeBank — subsequent authorizations decline immediately.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

SafeBank card UUID

Responses

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "status": "inactive",
  • "last4": "4242",
  • "safeAddress": "0x1111111111111111111111111111111111111111"
}

Unfreeze a card

Reactivates a frozen card.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

SafeBank card UUID

Responses

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "status": "inactive",
  • "last4": "4242",
  • "safeAddress": "0x1111111111111111111111111111111111111111"
}

Issue a card from a wallet

Issues a Safe-funded card drawing USDC from the wallet’s Safe, seeding its spend limits from the body. Sandbox-only (a Stripe cardholder is minted for the tenant on first use); live issuance requires KYB onboarding.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
walletId
required
string

Source wallet id (must be DEPLOYED).

Request Body schema: application/json
required
perTransactionUsd
object or null

Per-transaction USD cap. null clears it.

dailyUsd
object or null

Rolling 24h USD cap. null clears it.

weeklyUsd
object or null

Rolling ISO-week USD cap. null clears it.

monthlyUsd
object or null

Calendar-month USD cap. null clears it.

blockedMcc
Array of strings

MCCs to decline. Replaces the existing list.

allowedMcc
Array of strings or null

When set, only these MCCs are allowed. null clears the allowlist (allow anything not blocked).

agentId
string

Bind the card to an agent (its spend also accumulates under the agent).

Responses

Request samples

Content type
application/json
{
  • "perTransactionUsd": "250.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00",
  • "blockedMcc": [
    ],
  • "allowedMcc": [
    ],
  • "agentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890"
}

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "stripeCardId": "ic_1NXxxx",
  • "last4": "4242",
  • "safeAddress": "0x1111111111111111111111111111111111111111",
  • "status": "active"
}

offramp

Create a phone-addressed payment (routes quoted when eligible)

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
phone
required
string

Recipient phone (E.164).

amountUsd
required
string

USD amount (≤6 fraction digits).

chainId
number

Source chain id (default 84532).

fundingMode
string
Enum: "INTERNAL_BALANCE" "ONCHAIN_DEPOSIT" "SAFE_PROPOSAL"

How the sender funds the payment. v1: INTERNAL_BALANCE.

requestedDestinationId
string

One of the RECIPIENT's active destination ids (server-verified ownership).

speedPreference
string
Enum: "FASTEST" "CHEAPEST"

Responses

Request samples

Content type
application/json
{
  • "phone": "+15551234567",
  • "amountUsd": "25.00",
  • "chainId": 0,
  • "fundingMode": "INTERNAL_BALANCE",
  • "requestedDestinationId": "string",
  • "speedPreference": "FASTEST"
}

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "CREATED",
  • "recipientPhoneMasked": { },
  • "recipientTenantId": { },
  • "claimId": { },
  • "sourceChainKey": "string",
  • "sourceAssetId": "string",
  • "sourceAmountBaseUnits": "string",
  • "sourceFundingMode": "string",
  • "requestedDestinationId": { },
  • "selectedRouteQuoteId": { },
  • "holdReasons": [
    ],
  • "failureReason": { },
  • "deliveredAt": { },
  • "createdAt": "string",
  • "quotes": [
    ]
}

List corridor payments (sent or received)

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "payments": [
    ]
}

Fetch one corridor payment

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "CREATED",
  • "recipientPhoneMasked": { },
  • "recipientTenantId": { },
  • "claimId": { },
  • "sourceChainKey": "string",
  • "sourceAssetId": "string",
  • "sourceAmountBaseUnits": "string",
  • "sourceFundingMode": "string",
  • "requestedDestinationId": { },
  • "selectedRouteQuoteId": { },
  • "holdReasons": [
    ],
  • "failureReason": { },
  • "deliveredAt": { },
  • "createdAt": "string"
}

Current active route quotes

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "routes": [
    ]
}

Select a route quote (recipient only)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
routeQuoteId
required
string

Route quote id to select.

Responses

Request samples

Content type
application/json
{
  • "routeQuoteId": "string"
}

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "CREATED",
  • "recipientPhoneMasked": { },
  • "recipientTenantId": { },
  • "claimId": { },
  • "sourceChainKey": "string",
  • "sourceAssetId": "string",
  • "sourceAmountBaseUnits": "string",
  • "sourceFundingMode": "string",
  • "requestedDestinationId": { },
  • "selectedRouteQuoteId": { },
  • "holdReasons": [
    ],
  • "failureReason": { },
  • "deliveredAt": { },
  • "createdAt": "string"
}

Confirm the selected route — locks funds and starts execution (recipient only)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "CREATED",
  • "recipientPhoneMasked": { },
  • "recipientTenantId": { },
  • "claimId": { },
  • "sourceChainKey": "string",
  • "sourceAssetId": "string",
  • "sourceAmountBaseUnits": "string",
  • "sourceFundingMode": "string",
  • "requestedDestinationId": { },
  • "selectedRouteQuoteId": { },
  • "holdReasons": [
    ],
  • "failureReason": { },
  • "deliveredAt": { },
  • "createdAt": "string"
}

Cancel an unfunded payment (sender only)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "CREATED",
  • "recipientPhoneMasked": { },
  • "recipientTenantId": { },
  • "claimId": { },
  • "sourceChainKey": "string",
  • "sourceAssetId": "string",
  • "sourceAmountBaseUnits": "string",
  • "sourceFundingMode": "string",
  • "requestedDestinationId": { },
  • "selectedRouteQuoteId": { },
  • "holdReasons": [
    ],
  • "failureReason": { },
  • "deliveredAt": { },
  • "createdAt": "string"
}

claims

Inspect a claim link (public; the token is the authorization)

path Parameters
claimToken
required
string

Responses

Response samples

Content type
application/json
{
  • "amountUsd": "25.00",
  • "assetId": "string",
  • "chainKey": "eip155:84532",
  • "status": "string",
  • "expiresAt": "string",
  • "phoneMasked": "+1 ••• 4567"
}

Send a 6-digit code to the claim's stored phone (public)

path Parameters
claimToken
required
string

Responses

Response samples

Content type
application/json
{
  • "challengeId": "string",
  • "expiresAt": "string"
}

Confirm the phone code (public; 5 attempts per challenge)

path Parameters
claimToken
required
string
Request Body schema: application/json
required
challengeId
required
string

Challenge id returned by verify-phone.

code
required
string

6-digit code from the SMS.

Responses

Request samples

Content type
application/json
{
  • "challengeId": "string",
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "challengeId": "string",
  • "verified": true
}

Redeem a claim into your tenant (verified phone challenge + active destination)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
claimToken
required
string
Request Body schema: application/json
required
challengeId
required
string

A VERIFIED phone challenge id for this claim.

destinationId
required
string

One of the caller tenant's ACTIVE payout destination ids.

Responses

Request samples

Content type
application/json
{
  • "challengeId": "string",
  • "destinationId": "string"
}

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "status": "string",
  • "holdReasons": [
    ],
  • "quotes": [
    ]
}

Re-send the claim SMS with a fresh link (sender only, budgeted)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
claimId
required
string

Responses

Response samples

Content type
application/json
{
  • "expiresAt": "string"
}

Request an expired-claim refund (sender only; pre-expiry returns 409; idempotent)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
claimId
required
string

Responses

Response samples

Content type
application/json
{
  • "claimStatus": "string",
  • "paymentStatus": "string",
  • "refundTxHash": { }
}

capabilities

Self-describing platform capabilities

Returns the deployment environment, the EVM chains the platform is configured for (with USDC token addresses), and the feature flags that are actually available in this deployment. Computed from config; unbuilt features report false.

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "1",
  • "environment": "sandbox",
  • "chains": [
    ],
  • "features": {
    }
}

tenants

Create (bootstrap) a tenant

Creates the developer/business account that owns API keys and every API-platform resource. Authenticated with a Privy session — this is the one API-platform write that does not need a tenant to already exist. Idempotent: if the caller already owns a tenant, that tenant is returned.

Authorizations:
privyBearer
Request Body schema: application/json
required
name
string

Human-readable tenant name. Defaults to a generated name.

slug
string

URL-safe slug (lowercase letters, digits, hyphens). Auto-generated from the name when omitted; a numeric suffix is appended if the slug is taken.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Robotics",
  • "slug": "acme-robotics"
}

Response samples

Content type
application/json
{
  • "id": "b3f1c2a0-1111-2222-3333-444455556666",
  • "slug": "acme-robotics",
  • "name": "Acme Robotics",
  • "role": "OWNER",
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

Get the current tenant

Returns the tenant the caller is acting as — resolved from the Privy session's membership or from the developer API key.

Authorizations:
privyBearer

Responses

Response samples

Content type
application/json
{
  • "id": "b3f1c2a0-1111-2222-3333-444455556666",
  • "slug": "acme-robotics",
  • "name": "Acme Robotics",
  • "role": "OWNER",
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

members

Invite a member

Creates a PENDING member and returns a one-time invite token (share it with the invitee). They accept via POST /v1/tenants/members/accept, registering the address they will sign with.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
email
required
string

Invitee email.

displayName
string

Display name for the member.

role
string
Default: "MEMBER"
Enum: "ADMIN" "MEMBER"

Responses

Request samples

Content type
application/json
{
  • "email": "bob@acme.com",
  • "displayName": "Bob Jones",
  • "role": "ADMIN"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": { },
  • "displayName": { },
  • "role": "MEMBER",
  • "status": "PENDING",
  • "signerAddress": "0x83172d9A819b7895cEE10F4B52bB4Ec40114D39C",
  • "privyUserId": { },
  • "createdAt": "string",
  • "acceptedAt": { },
  • "inviteToken": "string"
}

List members

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "members": [
    ]
}

Revoke a member

Marks the member REVOKED. Does NOT remove on-chain Safe ownership — the response lists wallets where they are still an owner so you can remove them with an owner-admin tx.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "REVOKED",
  • "stillOwnerOfWalletIds": [ ]
}

Accept an invite

Token-authenticated (no API key needed). Activates the member and registers the EVM address they will sign with.

Request Body schema: application/json
required
token
required
string

The one-time invite token from the invite response.

signerAddress
required
string

The EVM address the member will sign with (their CLI signer or wallet address). Becomes the on-chain owner key when they are added to a Safe.

displayName
string

Optional display name override.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "signerAddress": "0x83172d9A819b7895cEE10F4B52bB4Ec40114D39C",
  • "displayName": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": { },
  • "displayName": { },
  • "role": "MEMBER",
  • "status": "PENDING",
  • "signerAddress": "0x83172d9A819b7895cEE10F4B52bB4Ec40114D39C",
  • "privyUserId": { },
  • "createdAt": "string",
  • "acceptedAt": { }
}

keys

Create an API key

Mints a developer API key for the caller’s tenant. The plaintext key is returned ONCE — store it immediately. Requires the keys:manage scope (Privy sessions and root keys hold it implicitly).

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
name
required
string

Human label for the key.

environment
string
Enum: "test" "live"

Environment. Defaults to test.

scopes
Array of strings
Items Enum: "wallets:read" "wallets:write" "wallets:fund" "payments:read" "payments:create" "payments:execute" "cards:read" "cards:issue" "cards:manage" "policies:read" "policies:write" "policies:evaluate" "agents:read" "agents:manage" "treasury:read" "treasury:write" "invoices:read" "invoices:write" "invoices:release" "invoices:pay" "ramps:read" "ramps:write" "keys:manage" "members:read" "members:manage" "contacts:read" "contacts:write" "identity:read" "identity:write" "status:read" "twofactor:read" "twofactor:manage" "*"

Granted permission scopes. Defaults to a read-only set. Use * for a root key. Agent keys (created via the agents API) cannot hold agents:manage / keys:manage / policies:write.

expiresAt
string

Optional ISO-8601 expiry. A key past its expiry fails auth.

Responses

Request samples

Content type
application/json
{
  • "name": "CI sandbox",
  • "environment": "test",
  • "scopes": [
    ],
  • "expiresAt": "2027-01-01T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "id": "c1a2b3d4-...",
  • "key": "sb_test_Ab12Cd34Ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "pubId": "Ab12Cd34Ef56",
  • "environment": "TEST",
  • "scopes": [
    ],
  • "expiresAt": null,
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

List API keys

Metadata only — never the secret.

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Revoke an API key

Soft-revokes the key (the row is kept for audit). Idempotent.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

API key id.

Responses

Rotate an API key

Mints a new secret with the same scopes/environment; the old secret keeps working for a 24-hour grace window, then auto-expires. Returns the new plaintext key once.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

API key id to rotate.

Responses

Response samples

Content type
application/json
{
  • "id": "c1a2b3d4-...",
  • "key": "sb_test_Ab12Cd34Ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "pubId": "Ab12Cd34Ef56",
  • "environment": "TEST",
  • "scopes": [
    ],
  • "expiresAt": null,
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

agents

Create an agent

Creates a tenant-owned agent principal.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
name
required
string

Human label for the agent.

Responses

Request samples

Content type
application/json
{
  • "name": "ap-bot"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "name": "ap-bot",
  • "status": "ACTIVE",
  • "createdAt": "2026-08-10T00:00:00.000Z"
}

List agents

Tenant-scoped, newest first.

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ]
}

Get an agent

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "name": "ap-bot",
  • "status": "ACTIVE",
  • "createdAt": "2026-08-10T00:00:00.000Z"
}

Suspend an agent

A suspended agent is declined (AGENT_SUSPENDED) on its next action.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "name": "ap-bot",
  • "status": "ACTIVE",
  • "createdAt": "2026-08-10T00:00:00.000Z"
}

Reactivate a suspended agent

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "name": "ap-bot",
  • "status": "ACTIVE",
  • "createdAt": "2026-08-10T00:00:00.000Z"
}

Get an agent’s spend limits

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Responses

Response samples

Content type
application/json
{
  • "agentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "perTransactionUsd": "50.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00"
}

Set an agent’s spend limits

Per-payment / daily / weekly / monthly USD caps enforced on every agent-initiated payment. Only the fields sent change; an explicit null clears a cap.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Request Body schema: application/json
required
perTransactionUsd
object or null

Per-payment USD cap. null clears it.

dailyUsd
object or null

Rolling 24h USD cap. null clears it.

weeklyUsd
object or null

Rolling ISO-week USD cap. null clears it.

monthlyUsd
object or null

Calendar-month USD cap. null clears it.

Responses

Request samples

Content type
application/json
{
  • "perTransactionUsd": "50.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00"
}

Response samples

Content type
application/json
{
  • "agentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "perTransactionUsd": "50.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00"
}

Mint an agent-scoped API key

Returns the plaintext key ONCE. Scopes are clamped to the agent ceiling — the key can never hold *, agents:manage, keys:manage, or policies:write.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Request Body schema: application/json
required
name
required
string

Human label for the key.

environment
string
Enum: "test" "live"

Environment. Defaults to test.

scopes
Array of strings
Items Enum: "wallets:read" "wallets:write" "wallets:fund" "payments:read" "payments:create" "payments:execute" "cards:read" "cards:issue" "cards:manage" "policies:read" "policies:evaluate" "agents:read" "treasury:read" "invoices:read" "invoices:write" "invoices:release" "invoices:pay" "ramps:read" "ramps:write" "members:read" "contacts:read" "contacts:write" "identity:read" "status:read" "twofactor:read"

Granted scopes. Clamped to the agent ceiling — an agent key can never hold *, agents:manage, keys:manage, or policies:write. Defaults to wallets:read + payments:read/create.

expiresAt
string

Optional ISO-8601 expiry. A key past its expiry fails auth.

Responses

Request samples

Content type
application/json
{
  • "name": "ap-bot ci",
  • "environment": "test",
  • "scopes": [
    ],
  • "expiresAt": "2027-01-01T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "id": "c1a2b3d4-...",
  • "key": "sb_test_Ab12Cd34Ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "pubId": "Ab12Cd34Ef56",
  • "environment": "TEST",
  • "scopes": [
    ],
  • "expiresAt": null,
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

Provision the agent's dedicated Safe

Creates a tenant-owned Safe (purpose AGENT) the agent’s card and payments draw from. One wallet per agent; owners are tenant signers (the agent holds no on-chain key). Deploys asynchronously — poll the wallet until DEPLOYED.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Request Body schema: application/json
required
required
Array of objects (WalletOwnerInput)

Safe owners (tenant signers).

threshold
number

Signature threshold. Defaults to 1.

chainId
number

EVM chain id. Defaults to the sandbox chain.

Responses

Request samples

Content type
application/json
{
  • "owners": [
    ],
  • "threshold": 1,
  • "chainId": 84532
}

Response samples

Content type
application/json
{
  • "agentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  • "walletId": "string",
  • "address": { },
  • "status": "PENDING_DEPLOYMENT",
  • "chainId": 84532,
  • "threshold": 1
}

Issue a Safe-funded card bound to the agent

Issues from the agent’s dedicated wallet (provision it first). Caps omitted from the body are seeded from the agent’s own limits, so the in-prod card gate enforces the agent’s caps synchronously. Sandbox only.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

Request Body schema: application/json
required
perTransactionUsd
object or null

Per-transaction USD cap. null clears it.

dailyUsd
object or null

Rolling 24h USD cap. null clears it.

weeklyUsd
object or null

Rolling ISO-week USD cap. null clears it.

monthlyUsd
object or null

Calendar-month USD cap. null clears it.

blockedMcc
Array of strings

MCCs to decline. Replaces the existing list.

allowedMcc
Array of strings or null

When set, only these MCCs are allowed. null clears the allowlist (allow anything not blocked).

Responses

Request samples

Content type
application/json
{
  • "perTransactionUsd": "250.00",
  • "dailyUsd": "500.00",
  • "weeklyUsd": "2000.00",
  • "monthlyUsd": "5000.00",
  • "blockedMcc": [
    ],
  • "allowedMcc": [
    ]
}

Response samples

Content type
application/json
{
  • "cardId": "6ee0b2a0-3c8c-4f49-9d12-bd55b15f02b1",
  • "stripeCardId": "ic_1NXxxx",
  • "last4": "4242",
  • "safeAddress": "0x1111111111111111111111111111111111111111",
  • "status": "active"
}

The agent's merged audit timeline

Newest-first merge of the agent’s payments, card authorizations, and policy decisions. Read-only.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Agent id

query Parameters
limit
number
Example: limit=50

Max items (1–200). Defaults to 50.

Responses

Response samples

Content type
application/json
{
  • "agentId": "string",
  • "items": [
    ]
}

Authorize an x402 payment

Screens the payTo (OFAC), enforces the agent policy + spend caps (reserve-at-sign), and returns a signed X-PAYMENT header to retry the 402-protected request with. The payer is the agent Safe; the authorization is verified on-chain (EIP-1271) and bounded by the SessionKeyValidator.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
scheme
required
string
Enum: "exact" "upto"

x402 payment scheme.

network
required
string

CAIP-2 network id (EVM only).

amount
required
string

Atomic token units (for upto, the ceiling).

asset
required
string

Token contract address (USDC).

payTo
required
string

Recipient address (screened as the counterparty).

maxTimeoutSeconds
required
number
domainName
string
Default: "USD Coin"

EIP-712 domain name hint (402 extra.name).

domainVersion
string
Default: "2"

EIP-712 domain version hint (402 extra.version).

resource
string

The protected resource URL (audit only).

Responses

Request samples

Content type
application/json
{
  • "scheme": "exact",
  • "network": "eip155:84532",
  • "amount": "10000",
  • "asset": "string",
  • "payTo": "string",
  • "maxTimeoutSeconds": 60,
  • "domainName": "USD Coin",
  • "domainVersion": "2",
  • "resource": "string"
}

Response samples

Content type
application/json
{
  • "xPayment": "string",
  • "nonce": "string",
  • "reservationId": "string",
  • "from": "string",
  • "payTo": "string",
  • "amountUsd": "string",
  • "authorization": {
    }
}

Report x402 settlement

Move a reservation from reserved to settled spend at the actual amount (upto ≤ ceiling) once the facilitator confirms the on-chain transfer. Idempotent per nonce.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
nonce
required
string

The EIP-3009 nonce returned by authorize.

txHash
required
string

Settlement transaction hash.

actualAmount
string

Actual settled atomic units (upto ≤ ceiling). Defaults to reserved.

Responses

Request samples

Content type
application/json
{
  • "nonce": "string",
  • "txHash": "string",
  • "actualAmount": "string"
}

Response samples

Content type
application/json
{
  • "nonce": "string",
  • "status": "SETTLED"
}

wallets

Create a multisig wallet

Creates a Safe for the caller’s tenant and fires the on-chain deploy asynchronously. Returns the predicted CREATE2 address immediately (usable before the proxy is mined). Defaults: Base Sepolia (84532), threshold 1.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
name
required
string

Human name for the wallet.

required
Array of objects (WalletOwnerInput)

On-chain owners. At least one; the first defaults to ADMIN_OWNER.

threshold
number

Signature threshold. Defaults to 1 (sandbox single-owner).

chainId
number

EVM chain id. Defaults to the platform default (Base Sepolia 84532).

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Treasury",
  • "owners": [
    ],
  • "threshold": 1,
  • "chainId": 84532
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": { },
  • "status": "PENDING_DEPLOYMENT",
  • "chainId": { },
  • "threshold": 0,
  • "predictedAddress": true,
  • "name": "string",
  • "owners": [
    ],
  • "balances": [
    ],
  • "createdAt": "string"
}

List wallets

Tenant-scoped, newest first.

Authorizations:
apiKeyAuthprivyBearer
query Parameters
skip
string
take
string

Responses

Response samples

Content type
application/json
{
  • "wallets": [
    ],
  • "total": 0,
  • "skip": 0,
  • "take": 0
}

Transactions awaiting an owner’s signature

Pending Safe transactions across your wallets. Pass ?owner=0x… to get only those a specific owner has not yet signed (their co-sign queue).

Authorizations:
apiKeyAuthprivyBearer
query Parameters
owner
string

Responses

Response samples

Content type
application/json
{
  • "pending": [
    ]
}

Get a Safe transaction (with collected signatures)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
txId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "walletId": "string",
  • "to": "string",
  • "value": "string",
  • "data": "string",
  • "safeTxHash": { },
  • "status": "string",
  • "signers": [
    ],
  • "signatureCount": 0,
  • "threshold": 0,
  • "createdAt": "string"
}

Get a wallet

Includes live on-chain balances.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": { },
  • "status": "PENDING_DEPLOYMENT",
  • "chainId": { },
  • "threshold": 0,
  • "predictedAddress": true,
  • "name": "string",
  • "owners": [
    ],
  • "balances": [
    ],
  • "createdAt": "string"
}

List a wallet’s Safe transactions

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
query Parameters
skip
string
take
string

Responses

Propose a Safe transaction

Builds and pins a SafeTx (to/value/data). Returns the safeTxHash to sign.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
to
required
string

Destination contract/EOA (EIP-55).

value
string

Native value in wei (decimal string). Defaults to "0".

data
string

Calldata hex. Defaults to 0x.

ownerAddress
string

Owner address to act as (must be a registered on-chain owner). Optional when the wallet has exactly one on-chain owner.

Responses

Request samples

Content type
application/json
{
  • "to": "0x036CbD…",
  • "value": "0",
  • "data": "0xa9059cbb…",
  • "ownerAddress": "string"
}

Submit an owner signature

The signer is recovered from the raw secp256k1 signature over the safeTxHash and must be a registered on-chain owner. When the threshold is met the tx becomes executable.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
txId
required
string
Request Body schema: application/json
required
signature
required
string

Raw secp256k1 signature over the 32-byte safeTxHash (NOT personal_sign).

Responses

Request samples

Content type
application/json
{
  • "signature": "0x…"
}

Execute a threshold-met transaction on-chain

Authorizations:
apiKeyAuthprivyBearer
path Parameters
txId
required
string
Request Body schema: application/json
required
ownerAddress
string

Owner address to act as. Optional for single-owner wallets.

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Cancel a pending transaction

Authorizations:
apiKeyAuthprivyBearer
path Parameters
txId
required
string
Request Body schema: application/json
required
ownerAddress
string

Owner address to act as. Optional for single-owner wallets.

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Propose adding an owner

Proposes an owner-admin SafeTx; the wallet threshold of owners must sign it.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
newOwner
required
string

New owner address (EIP-55).

threshold
required
number

Resulting signature threshold (1..ownerCount+1).

role
string
Enum: "ADMIN_OWNER" "FINANCE_OWNER" "MERCHANT_OPERATOR"

DB role for the new owner (default FINANCE_OWNER).

ownerAddress
string

Acting owner (ADMIN_OWNER). Optional if sole owner.

Responses

Request samples

Content type
application/json
{
  • "newOwner": "string",
  • "threshold": 2,
  • "role": "ADMIN_OWNER",
  • "ownerAddress": "string"
}

Propose removing an owner

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
addr
required
string

Owner address to remove

Request Body schema: application/json
required
threshold
required
number

Resulting signature threshold (1..ownerCount-1).

ownerAddress
string

Acting owner (ADMIN_OWNER). Optional if sole owner.

Responses

Request samples

Content type
application/json
{
  • "threshold": 1,
  • "ownerAddress": "string"
}

Propose swapping an owner for a new address

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
addr
required
string

Existing owner address to replace

Request Body schema: application/json
required
newOwner
required
string

The replacement owner address (EIP-55).

ownerAddress
string

Acting owner (ADMIN_OWNER). Optional if sole owner.

Responses

Request samples

Content type
application/json
{
  • "newOwner": "string",
  • "ownerAddress": "string"
}

Propose changing the signature threshold

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
threshold
required
number

New signature threshold (1..ownerCount).

ownerAddress
string

Acting owner (ADMIN_OWNER). Optional if sole owner.

Responses

Request samples

Content type
application/json
{
  • "threshold": 2,
  • "ownerAddress": "string"
}

faucet

Fund a wallet from the sandbox faucet

Sends platform-funded test USDC (default) or test ETH to the wallet. TEST environment only; capped at 1000 USDC / 0.02 ETH per drip and rate-limited per wallet and tenant.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Wallet id to fund.

Request Body schema: application/json
required
asset
string
Enum: "usdc" "eth"

Asset to drip. Defaults to usdc.

amount
string

Human decimal amount (e.g. "250" USDC, "0.01" ETH). Defaults to a per-asset default. Capped at 1000 USDC / 0.02 ETH per drip.

Responses

Request samples

Content type
application/json
{
  • "asset": "usdc",
  • "amount": "250"
}

Response samples

Content type
application/json
{
  • "id": "d1a2b3c4-...",
  • "walletId": "w1",
  • "asset": "usdc",
  • "amount": "250",
  • "chainId": 84532,
  • "status": "SUBMITTED",
  • "txHash": { },
  • "failureReason": { },
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

List faucet drips

Tenant-scoped, newest first.

Authorizations:
apiKeyAuthprivyBearer
query Parameters
walletId
string

Responses

Response samples

Content type
application/json
{
  • "drips": [
    ]
}

Get a faucet drip

Authorizations:
apiKeyAuthprivyBearer
path Parameters
dripId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "d1a2b3c4-...",
  • "walletId": "w1",
  • "asset": "usdc",
  • "amount": "250",
  • "chainId": 84532,
  • "status": "SUBMITTED",
  • "txHash": { },
  • "failureReason": { },
  • "createdAt": "2026-08-09T12:00:00.000Z"
}

directory

Resolve a handle or email to a destination

Exact match only. Email resolution requires the target to have opted in.

Authorizations:
apiKeyAuthprivyBearer
query Parameters
handle
string
email
string

Responses

Response samples

Content type
application/json
{
  • "handle": "acme-treasury",
  • "displayName": { },
  • "address": "0x7Fb2…c41A",
  • "chainId": 84532,
  • "verified": true
}

Claim or update your payment handle

Points an @handle at one of your wallets so others can pay you by name.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
handle
required
string

Handle to claim (without the @).

walletId
required
string

Wallet id this handle resolves to.

discoverableByEmail
boolean

Opt in to email-based resolution.

email
string

Contact email for email resolution.

Responses

Request samples

Content type
application/json
{
  • "handle": "acme-treasury",
  • "walletId": "w1",
  • "discoverableByEmail": false,
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "handle": "acme-treasury",
  • "displayName": { },
  • "address": "0x7Fb2…c41A",
  • "chainId": 84532,
  • "verified": true
}

contacts

Save a payee to the address book

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
label
required
string

Short label used as @label at pay time.

displayName
string
notes
string
required
object (ContactDestinationInput)

Responses

Request samples

Content type
application/json
{
  • "label": "acme",
  • "displayName": "Acme Robotics",
  • "notes": "string",
  • "destination": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "displayName": { },
  • "notes": { },
  • "destination": {
    },
  • "createdAt": "string"
}

List saved contacts

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ]
}

Get a contact

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "displayName": { },
  • "notes": { },
  • "destination": {
    },
  • "createdAt": "string"
}

Update a contact

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
displayName
string
notes
string
object (ContactDestinationInput)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "notes": "string",
  • "destination": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "displayName": { },
  • "notes": { },
  • "destination": {
    },
  • "createdAt": "string"
}

Delete a contact

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

identity

Start a KYC or KYB verification session

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
kind
required
string
Enum: "KYC" "KYB"

KYC verifies a member; KYB the tenant.

memberId
string

TenantMember id — required for KYC, ignored for KYB.

legalName
string

Subject legal name. Defaults to the member display name (KYC) or tenant name (KYB).

email
string

Subject contact email; defaults to the member email.

country
string

ISO-3166 alpha-2 country code.

Responses

Request samples

Content type
application/json
{
  • "kind": "KYC",
  • "memberId": "string",
  • "legalName": "string",
  • "email": "string",
  • "country": "DE"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "KYC",
  • "subjectType": "TENANT",
  • "subjectId": "string",
  • "legalName": "string",
  • "status": "CREATED",
  • "requirements": [
    ],
  • "credentialId": { },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": { }
}

List verification sessions

Authorizations:
apiKeyAuthprivyBearer
query Parameters
subject_type
required
string
subject_id
required
string

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

Get a verification session

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "KYC",
  • "subjectType": "TENANT",
  • "subjectId": "string",
  • "legalName": "string",
  • "status": "CREATED",
  • "requirements": [
    ],
  • "credentialId": { },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": { }
}

Cancel a verification session

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "KYC",
  • "subjectType": "TENANT",
  • "subjectId": "string",
  • "legalName": "string",
  • "status": "CREATED",
  • "requirements": [
    ],
  • "credentialId": { },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": { }
}

Advance a sandbox session one step (TEST environment, mock provider only)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "KYC",
  • "subjectType": "TENANT",
  • "subjectId": "string",
  • "legalName": "string",
  • "status": "CREATED",
  • "requirements": [
    ],
  • "credentialId": { },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": { }
}

List credentials

Authorizations:
apiKeyAuthprivyBearer
query Parameters
subject_type
required
string
subject_id
required
string

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Get a credential

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "PERSON_IDENTITY",
  • "subjectType": "TENANT",
  • "subjectId": "string",
  • "status": "ACTIVE",
  • "legalName": "string",
  • "issuedAt": "string",
  • "expiresAt": { },
  • "revokedAt": { },
  • "revokedReason": { }
}

Mint a one-time cross-device handoff link (rendered as a QR code)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "expiresAt": "string"
}

Save a payout destination (requires an active KYB credential)

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
type
string
Enum: "ONCHAIN_WALLET" "PAYPAL" "VENMO" "US_BANK_ACH" "SEPA" "SAFEBANK_BALANCE"

Defaults to ONCHAIN_WALLET when an address is supplied (legacy shape).

asset
string

Asset symbol (on-chain types).

network
string

Network key, lowercase (on-chain types).

address
string

Receiving address, stored verbatim (case-sensitive).

email
string

PayPal email.

phone
string

E.164 phone (PayPal/Venmo).

handle
string

Venmo handle (without @).

routingNumber
string

US ABA routing number (US_BANK_ACH).

accountNumber
string

US bank account number (US_BANK_ACH).

iban
string

IBAN (SEPA).

country
string

ISO-3166 alpha-2 country.

currency
string

ISO-4217 payout currency (fiat rails).

label
string

Display label override.

Responses

Request samples

Content type
application/json
{
  • "type": "ONCHAIN_WALLET",
  • "asset": "USDT",
  • "network": "tron",
  • "address": "string",
  • "email": "string",
  • "phone": "string",
  • "handle": "string",
  • "routingNumber": "string",
  • "accountNumber": "string",
  • "iban": "string",
  • "country": "string",
  • "currency": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

List payout destinations

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "destinations": [
    ]
}

Fetch one payout destination

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

Update label/priority/fallback consent (the identifier itself is immutable)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
label
string

Display label.

priority
number

Ordering preference among own destinations.

allowAutomaticFallback
boolean

Consent to automatic fallback routing to this destination (spec rule 14).

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "priority": 0,
  • "allowAutomaticFallback": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

Revoke a destination (soft — history survives, routing excludes it)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

Make a VERIFIED destination the default payout preference

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

Verify destination ownership (sandbox only until the proof method ships)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "STABLECOIN_ADDRESS",
  • "asset": { },
  • "network": { },
  • "address": { },
  • "provider": { },
  • "country": { },
  • "currency": { },
  • "maskedLabel": "string",
  • "status": "PENDING_VERIFICATION",
  • "ownershipStatus": "DECLARED",
  • "verificationCredentialId": { },
  • "priority": 0,
  • "allowAutomaticFallback": true,
  • "isDefault": true,
  • "consentedAt": { },
  • "verifiedAt": { },
  • "revokedAt": { },
  • "createdAt": "string"
}

Evaluate credential requirements for an action

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
action
required
string
Enum: "payments.create" "invoices.pay" "ramps.offramp"

Responses

Request samples

Content type
application/json
{
  • "action": "payments.create"
}

Response samples

Content type
application/json
{
  • "eligible": true,
  • "mode": "off",
  • "requirements": [
    ]
}

2fa

List your enrolled second factors

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "factors": [
    ],
  • "requiredFactors": 0,
  • "usableFactors": 0
}

Begin enrolling a second factor

Sends a confirmation code (EMAIL/SMS) or returns a TOTP secret. The factor stays PENDING until POST /v1/2fa/factors/{id}/verify proves control of the channel.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
type
required
string
Enum: "EMAIL" "SMS" "TOTP" "PRIVY_MFA"
email
string

Required when type=EMAIL.

phoneE164
string

Required when type=SMS. E.164, e.g. +15551234567.

label
string

Optional friendly name, e.g. "work phone".

Responses

Request samples

Content type
application/json
{
  • "type": "EMAIL",
  • "email": "string",
  • "phoneE164": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "factorId": "string",
  • "type": "EMAIL",
  • "status": "string",
  • "hint": "string",
  • "secretBase32": "string",
  • "otpauthUri": "string",
  • "signerAddress": "string"
}

Prove control of a channel and activate the factor

Authorizations:
apiKeyAuthprivyBearer
path Parameters
factorId
required
string
Request Body schema: application/json
required
code
string

6-digit code (EMAIL / SMS / TOTP).

signature
string

EIP-712 signature (PRIVY_MFA).

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "EMAIL",
  • "status": "PENDING",
  • "label": { },
  • "hint": "string",
  • "verifiedAt": { },
  • "usableAt": { },
  • "usableNow": true,
  • "lastUsedAt": { },
  • "createdAt": "string"
}

Revoke a second factor

Effective immediately. Refused if it would drop your usable factors below the tenant requirement, or leave you with only email/SMS (which would make your funds unreachable during a provider outage).

Authorizations:
apiKeyAuthprivyBearer
path Parameters
factorId
required
string

Responses

Read a pending transaction challenge

Authorizations:
apiKeyAuthprivyBearer
path Parameters
challengeId
required
string

Responses

Deliver a code for one factor

Also used to resend. The message states the amount and destination — that is the anti-phishing control, so compare it against what you are actually sending.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
challengeId
required
string
Request Body schema: application/json
required
factorId
required
string

Which enrolled factor to deliver the code to.

Responses

Request samples

Content type
application/json
{
  • "factorId": "string"
}

Verify one factor against a challenge

Repeat until satisfiedFactors reaches requiredFactors, then replay the original request with the X-SafeBank-2FA-Challenge header.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
challengeId
required
string
Request Body schema: application/json
required
factorId
required
string
code
string

6-digit code (EMAIL / SMS / TOTP).

signature
string

EIP-712 signature (PRIVY_MFA).

Responses

Request samples

Content type
application/json
{
  • "factorId": "string",
  • "code": "string",
  • "signature": "string"
}

Read the tenant transaction-protection settings

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "coolingOffSeconds": 0,
  • "thresholdUsd": "string",
  • "requiredFactors": 0,
  • "updatedAt": { }
}

Update the tenant transaction-protection settings

Owner/admin user sessions only — never an API key, whatever scopes it holds. The cooling-off window cannot be set below 24h while protection is enabled.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
enabled
boolean
coolingOffSeconds
number >= 86400

Minimum 86400 (24h) while enabled.

thresholdUsd
string
requiredFactors
number >= 1

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "coolingOffSeconds": 86400,
  • "thresholdUsd": "100",
  • "requiredFactors": 1
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "coolingOffSeconds": 0,
  • "thresholdUsd": "string",
  • "requiredFactors": 0,
  • "updatedAt": { }
}

payments

Create a payment

Resolves the destination, OFAC-screens the recipient, and proposes a USDC transfer on the source Safe. Returns the payment with its safeTxHash to sign.

Authorizations:
apiKeyAuthprivyBearer
header Parameters
x-safebank-2fa-challenge
string

A satisfied two-factor challenge id, replayed after a 403 TWOFA_REQUIRED. Sent as a HEADER rather than a body field so the request body — and therefore the Idempotency-Key hash — is byte-identical between the original call and the retry.

Request Body schema: application/json
required
sourceWalletId
required
string

Wallet to pay from.

required
object (PaymentDestinationInput)
required
object (PaymentAmountInput)
memo
string

Free-text memo.

ownerAddress
string

Owner address to act as (must be a registered on-chain owner). Optional for single-owner wallets.

Responses

Request samples

Content type
application/json
{
  • "sourceWalletId": "w1",
  • "destination": {
    },
  • "amount": {
    },
  • "memo": "string",
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceWalletId": "string",
  • "destinationType": "handle",
  • "destinationHandle": { },
  • "destinationAddress": "string",
  • "destinationChainId": 0,
  • "asset": "usdc",
  • "amount": "25.00",
  • "status": "CREATED",
  • "safeTxHash": { },
  • "executedTxHash": { },
  • "memo": { },
  • "failureReason": { },
  • "createdAt": "string"
}

List payments

Tenant-scoped, newest first.

Authorizations:
apiKeyAuthprivyBearer
query Parameters
skip
string
take
string

Responses

Response samples

Content type
application/json
{
  • "payments": [
    ],
  • "total": 0,
  • "skip": 0,
  • "take": 0
}

Get a payment

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceWalletId": "string",
  • "destinationType": "handle",
  • "destinationHandle": { },
  • "destinationAddress": "string",
  • "destinationChainId": 0,
  • "asset": "usdc",
  • "amount": "25.00",
  • "status": "CREATED",
  • "safeTxHash": { },
  • "executedTxHash": { },
  • "memo": { },
  • "failureReason": { },
  • "createdAt": "string"
}

Sign a payment

Submits an owner signature over the safeTxHash. Once the threshold is met the payment auto-executes on-chain.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
signature
required
string

Raw secp256k1 signature over the safeTxHash.

Responses

Request samples

Content type
application/json
{
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceWalletId": "string",
  • "destinationType": "handle",
  • "destinationHandle": { },
  • "destinationAddress": "string",
  • "destinationChainId": 0,
  • "asset": "usdc",
  • "amount": "25.00",
  • "status": "CREATED",
  • "safeTxHash": { },
  • "executedTxHash": { },
  • "memo": { },
  • "failureReason": { },
  • "createdAt": "string"
}

Execute a threshold-met payment on-chain

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
ownerAddress
string

Owner address to act as. Optional for single-owner wallets.

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceWalletId": "string",
  • "destinationType": "handle",
  • "destinationHandle": { },
  • "destinationAddress": "string",
  • "destinationChainId": 0,
  • "asset": "usdc",
  • "amount": "25.00",
  • "status": "CREATED",
  • "safeTxHash": { },
  • "executedTxHash": { },
  • "memo": { },
  • "failureReason": { },
  • "createdAt": "string"
}

Cancel a pending payment

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
ownerAddress
string

Owner address to act as. Optional for single-owner wallets.

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceWalletId": "string",
  • "destinationType": "handle",
  • "destinationHandle": { },
  • "destinationAddress": "string",
  • "destinationChainId": 0,
  • "asset": "usdc",
  • "amount": "25.00",
  • "status": "CREATED",
  • "safeTxHash": { },
  • "executedTxHash": { },
  • "memo": { },
  • "failureReason": { },
  • "createdAt": "string"
}

treasury

Create a treasury account

Creates one Safe per bucket (202 — CREATE2 addresses are usable immediately, deployment is async). Sandbox-only for now.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
name
required
string

Treasury name.

required
Array of objects (WalletOwnerInput)

Safe owners applied to every bucket wallet.

threshold
number

Signature threshold per bucket Safe. Defaults to 1.

chainId
number

EVM chain id. Defaults to Base Sepolia (84532).

required
Array of objects (TreasuryBucketInput)

1-8 buckets, one Safe each.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Treasury",
  • "owners": [
    ],
  • "threshold": 0,
  • "chainId": 0,
  • "buckets": [
    ]
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "name": "string",
  • "buckets": [
    ],
  • "totalUsd": { },
  • "createdAt": "string"
}

List treasury accounts

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "total": 0
}

Get a treasury account

Live bucket balances, drift vs targetBps, and accrued simulated yield. A bucket whose balance cannot be read right now reports null (never zero).

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "name": "string",
  • "buckets": [
    ],
  • "totalUsd": { },
  • "createdAt": "string"
}

Create a rule

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
type
required
string
Enum: "SWEEP_EXCESS" "TOP_UP" "REBALANCE_TO_TARGET"
sourceBucketId
string

Source bucket id (SWEEP_EXCESS / TOP_UP).

destBucketId
string

Destination bucket id (SWEEP_EXCESS / TOP_UP).

thresholdUsd
string

SWEEP_EXCESS: balance above this is swept. TOP_UP: trigger level (defaults to targetUsd).

targetUsd
string

TOP_UP: refill the destination back up to this level.

intervalSeconds
number

Minimum seconds between fires. Default 3600.

enabled
boolean

Rules are enabled by default.

Responses

Request samples

Content type
application/json
{
  • "type": "SWEEP_EXCESS",
  • "sourceBucketId": "string",
  • "destBucketId": "string",
  • "thresholdUsd": "1000.00",
  • "targetUsd": "500.00",
  • "intervalSeconds": 0,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "ruleId": "string",
  • "accountId": "string",
  • "type": "SWEEP_EXCESS",
  • "sourceBucketId": { },
  • "destBucketId": { },
  • "thresholdUsd": { },
  • "targetUsd": { },
  • "intervalSeconds": 0,
  • "enabled": true,
  • "lastFiredAt": { },
  • "createdAt": "string"
}

List rules

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "total": 0
}

Update a rule (thresholds / cadence / enabled)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
ruleId
required
string
Request Body schema: application/json
required
thresholdUsd
string
targetUsd
string
intervalSeconds
number
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "thresholdUsd": "string",
  • "targetUsd": "string",
  • "intervalSeconds": 0,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "ruleId": "string",
  • "accountId": "string",
  • "type": "SWEEP_EXCESS",
  • "sourceBucketId": { },
  • "destBucketId": { },
  • "thresholdUsd": { },
  • "targetUsd": { },
  • "intervalSeconds": 0,
  • "enabled": true,
  • "lastFiredAt": { },
  • "createdAt": "string"
}

Delete a rule

Authorizations:
apiKeyAuthprivyBearer
path Parameters
ruleId
required
string

Responses

Propose a manual sweep

Proposes a bucket-to-bucket USDC Payment. Execution requires owner signatures via the payments API (a 1-of-1 Safe completes in a single sign call).

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
sourceBucketId
required
string

Bucket to move USDC out of.

destBucketId
required
string

Bucket to move USDC into.

amountUsd
required
string

USD amount to move.

ownerAddress
string

Acting owner for the proposal (required when the Safe has multiple owners).

Responses

Request samples

Content type
application/json
{
  • "sourceBucketId": "string",
  • "destBucketId": "string",
  • "amountUsd": "250.00",
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "sweepId": "string",
  • "accountId": "string",
  • "ruleId": { },
  • "sourceBucketId": "string",
  • "destBucketId": "string",
  • "amountUsd": "string",
  • "status": "PROPOSED",
  • "paymentId": { },
  • "paymentStatus": { },
  • "failureReason": { },
  • "createdAt": "string"
}

List sweeps

Includes the live status of each sweep’s linked payment.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "sweeps": [
    ],
  • "total": 0
}

ramps

Create a ramp

on = credit the wallet Safe with USDC (fiat debit simulated; completes immediately). off = propose a Safe debit to the liquidation address — owners sign the linked payment and the (simulated) fiat payout confirms when it executes. Sandbox-only.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
walletId
required
string

Wallet whose Safe is credited (on) or debited (off).

direction
required
string
Enum: "on" "off"

on = fiat->USDC, off = USDC->fiat.

amount
required
string

USD amount.

provider
string
Default: "simulated"
Enum: "simulated" "privy" "stripe" "visa" "ousd"

Ramp provider. Only simulated is live in the sandbox today.

Responses

Request samples

Content type
application/json
{
  • "walletId": "string",
  • "direction": "on",
  • "amount": "100.00",
  • "provider": "simulated"
}

Response samples

Content type
application/json
{
  • "rampId": "string",
  • "walletId": "string",
  • "direction": "ON",
  • "provider": "simulated",
  • "amountUsd": "string",
  • "status": "SUBMITTED",
  • "txHash": { },
  • "paymentId": { },
  • "paymentStatus": { },
  • "fiatRef": { },
  • "simulated": true,
  • "failureReason": { },
  • "createdAt": "string"
}

List ramps

Authorizations:
apiKeyAuthprivyBearer
query Parameters
walletId
string

Responses

Response samples

Content type
application/json
{
  • "ramps": [
    ],
  • "total": 0
}

Get a ramp

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "rampId": "string",
  • "walletId": "string",
  • "direction": "ON",
  • "provider": "simulated",
  • "amountUsd": "string",
  • "status": "SUBMITTED",
  • "txHash": { },
  • "paymentId": { },
  • "paymentStatus": { },
  • "fiatRef": { },
  • "simulated": true,
  • "failureReason": { },
  • "createdAt": "string"
}

policies

Create a policy

Compiles the document to an immutable v1 (IR + sha256) and makes it active.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
name
required
string

Human name for the policy.

document
required
object

The policy document (schemaVersion 1): limits (per-txn/daily/weekly/monthly USD), mcc (blocked/allowed), counterparties (blocked). Compiled to an immutable versioned IR.

Responses

Request samples

Content type
application/json
{
  • "name": "AP bot guardrails",
  • "document": {
    }
}

Response samples

Content type
application/json
{
  • "policyId": "string",
  • "name": "string",
  • "status": "ACTIVE",
  • "activeVersionId": { },
  • "activeVersion": { },
  • "createdAt": "string"
}

List policies

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "total": 0
}

Evaluate a policy (dry-run)

Deterministically tests a hypothetical transaction against a policy (by id or by the policy attached to a subject) using the same engine that gates live authorizations. Returns allow/deny + a per-rule trace and writes a DecisionLog audit row.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
policyId
string

Evaluate a specific policy id (else the one attached to the subject).

subjectType
string
Enum: "wallet" "card" "agent" "treasury_account"

Resolve the attached policy.

subjectId
string
amountUsd
required
string

Transaction USD amount to test.

mcc
string

4-digit MCC to test.

counterparty
string

Counterparty address to test.

Responses

Request samples

Content type
application/json
{
  • "policyId": "string",
  • "subjectType": "wallet",
  • "subjectId": "string",
  • "amountUsd": "120.00",
  • "mcc": "5411",
  • "counterparty": "string"
}

Response samples

Content type
application/json
{
  • "allow": true,
  • "reason": { },
  • "policyId": { },
  • "policyVersion": { },
  • "sha256": { },
  • "ruleTrace": [
    ],
  • "decisionLogId": "string"
}

Get a policy

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "policyId": "string",
  • "name": "string",
  • "status": "ACTIVE",
  • "activeVersionId": { },
  • "activeVersion": { },
  • "createdAt": "string"
}

Archive a policy

Archives the policy and detaches it from every subject.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Commit a new version

Appends an immutable version and makes it the active one.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
document
required
object

A new document — committed as the next immutable version.

Responses

Request samples

Content type
application/json
{
  • "document": { }
}

Response samples

Content type
application/json
{
  • "versionId": "string",
  • "version": 0,
  • "sha256": "string",
  • "ir": { },
  • "createdAt": "string"
}

List a policy’s versions

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "total": 0
}

Attach a policy to a subject

Binds the policy to a wallet / card / agent / treasury account. One active policy per subject. Attachments scope dry-run evaluation today; live gating is a later increment.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
subjectType
required
string
Enum: "wallet" "card" "agent" "treasury_account"
subjectId
required
string

Id of the wallet / card / agent / treasury account.

Responses

Request samples

Content type
application/json
{
  • "subjectType": "wallet",
  • "subjectId": "string"
}

Response samples

Content type
application/json
{
  • "attachmentId": "string",
  • "policyId": "string",
  • "subjectType": "wallet",
  • "subjectId": "string",
  • "attachedAt": "string"
}

List a policy’s active attachments

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Detach a policy from a subject

Authorizations:
apiKeyAuthprivyBearer
path Parameters
attachmentId
required
string

Responses

invoices

Create an invoice (draft)

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
payeeName
string

Human label for the payee.

description
string

What the invoice is for.

amountUsd
required
string

Amount due, USD.

payerAddress
required
string

Payer address (funds the hold Safe).

payeeAddress
required
string

Payee address (receives a release).

arbiterAddress
string

Platform arbiter address (tie-break owner). Defaults to the platform arbiter.

chainId
number

EVM chain id. Defaults to Base Sepolia (84532).

expiresAt
string

ISO-8601 auto-expiry for the unfunded invoice.

Responses

Request samples

Content type
application/json
{
  • "payeeName": "Volt Components",
  • "description": "string",
  • "amountUsd": "120.00",
  • "payerAddress": "0x1111…",
  • "payeeAddress": "0x2222…",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "expiresAt": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

List invoices

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "invoices": [
    ],
  • "total": 0
}

Send a verifiable bill to another tenant

The caller is the sender: targets the recipient by @handle or wallet address and carries an EIP-712 InvoiceAuthorization signed by a registered member key.

Authorizations:
apiKeyAuthprivyBearer
Request Body schema: application/json
required
toHandle
string

Recipient's SafeBank @handle (or use toAddress).

toAddress
string

Recipient's wallet address (or use toHandle).

amountUsd
required
string

Amount due, USD.

payeeAddress
required
string

Address that receives payment (the sender).

payeeName
string

Human label for the payee (bound by docHash).

description
string

What the bill is for (bound by docHash).

chainId
number

EVM chain id. Defaults to the payer wallet chain.

senderAddress
required
string

Address that SIGNED the authorization (a member key).

signature
required
string

EIP-712 InvoiceAuthorization signature.

sigNonce
required
string

Single-use replay nonce (uint256 as a decimal string).

sigExpiresAt
required
string

ISO-8601 authorization expiry.

sigDocHash
string

sha256 of the signed human-readable terms (bytes32).

domainChainId
number

EIP-712 domain chainId (defaults to the bill chainId).

domainVerifyingContract
string

EIP-712 domain verifyingContract anchor.

Responses

Request samples

Content type
application/json
{
  • "toHandle": "string",
  • "toAddress": "string",
  • "amountUsd": "120.00",
  • "payeeAddress": "string",
  • "payeeName": "string",
  • "description": "string",
  • "chainId": 0,
  • "senderAddress": "string",
  • "signature": "string",
  • "sigNonce": "string",
  • "sigExpiresAt": "string",
  • "sigDocHash": "string",
  • "domainChainId": 0,
  • "domainVerifyingContract": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

List inbound bills addressed to us

Authorizations:
apiKeyAuthprivyBearer
query Parameters
verification
string
Enum: "UNVERIFIED" "VERIFIED" "FAILED"

Responses

Response samples

Content type
application/json
{
  • "bills": [
    ],
  • "total": 0
}

Get one inbound bill

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

Get an invoice

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Send an invoice

Provisions the 2-of-3 hold Safe (202 — async deploy) and returns funding info.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Mark an invoice delivered (attach evidence)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
evidence
string

Delivery evidence (note / URL / reference).

Responses

Request samples

Content type
application/json
{
  • "evidence": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Release funds to the payee

Proposes the release payment; two of the three owners must sign to execute it.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
ownerAddress
string

Acting owner for the release/refund proposal (defaults to the sole on-chain owner).

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Refund funds to the payer

Proposes the refund payment; two of the three owners must sign to execute it.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
ownerAddress
string

Acting owner for the release/refund proposal (defaults to the sole on-chain owner).

Responses

Request samples

Content type
application/json
{
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Cancel an unfunded invoice

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "arbiterAddress": "string",
  • "chainId": 0,
  • "status": "DRAFT",
  • "holdWalletId": { },
  • "holdAddress": { },
  • "releasePaymentId": { },
  • "refundPaymentId": { },
  • "expiresAt": { },
  • "createdAt": "string"
}

Re-run verification on an inbound bill

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

Accept an inbound bill (overlay)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

Decline an inbound bill (overlay)

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

Pay an inbound bill from one of our wallets

Direct payment to the payee; rides M-of-N if the source wallet is multi-owner.

Authorizations:
apiKeyAuthprivyBearer
path Parameters
id
required
string
Request Body schema: application/json
required
sourceWalletId
required
string

The wallet to pay the bill from.

ownerAddress
string

Acting owner for the payment (if the wallet is M-of-N).

Responses

Request samples

Content type
application/json
{
  • "sourceWalletId": "string",
  • "ownerAddress": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "amountUsd": "string",
  • "payerAddress": "string",
  • "payeeAddress": "string",
  • "payeeName": { },
  • "description": { },
  • "chainId": 0,
  • "payerTenantId": { },
  • "senderTenantId": { },
  • "senderAddress": { },
  • "verificationStatus": "UNVERIFIED",
  • "payerDecision": "ACCEPTED",
  • "payerPaymentId": { },
  • "sigExpiresAt": { },
  • "createdAt": "string"
}

Public invoice view (unauthenticated)

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "string",
  • "payeeName": { },
  • "description": { },
  • "amountUsd": "string",
  • "status": "DRAFT",
  • "holdAddress": { },
  • "chainId": 0
}

status

Account summary: balance, bills owed, activity, agent spend

Authorizations:
apiKeyAuthprivyBearer

Responses

Response samples

Content type
application/json
{
  • "netBalanceUsd": "string",
  • "balancePartial": true,
  • "wallets": [
    ],
  • "billsOwed": {
    },
  • "recentActivity": [
    ],
  • "agentSpend": [
    ],
  • "generatedAt": "string"
}