Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getovra.com/llms.txt

Use this file to discover all available pages before exploring further.

Collect closes the loop on agent-native economies — your agent doesn’t only spend, it can also earn. Issue a payment request and the counterparty pays from another Ovra wallet (instant, free) or via SEPA with reference matching (external).
Internal Ovra-to-Ovra works today. External SEPA inbound matching is on the roadmap and is currently rejected by the /settle endpoint. See the status table below.

​
Why this matters

If your agent does work that someone else paid for — services, goods, microtransactions, API calls — you need a way to collect. Without Collect, “agent payments” is a one-way street. With it, agents can run businesses.

​
The payment-request model

FieldDescription
idpr_*
destinationWalletIdWhere settled funds land
amountEurosEUR amount, ≤ 1,000,000
descriptionFree text; surfaces in the payer view
counterpartyOwnerIdSet for internal requests (other Ovra customer)
sepaInstructions{ iban, bic, reference } for external requests; reference is OVRA-PR-<hex>
payerName / payerEmailOptional — surfaces on the payer page
agentIdOptional — bind the request to a specific agent
expiresAtOptional TTL (max 30 days)
statuspending → paid · expired · cancelled

​
Operations

EndpointPurpose
POST /claim/requestsCreate a request. Pass counterpartyOwnerId for internal, omit for external.
GET /claim/requestsList your requests. Filter status, use inbound=true for the payer view.
GET /claim/requests/:idDetail — owner or counterparty allowed.
POST /claim/requests/:id/settleInternal only. Atomic wallet→wallet debit/credit + ledger + transfer row.
POST /claim/requests/:id/cancelCancel an unpaid request.
GET /claim/requests/:id/payPublic payer page — no auth required.
The pillar is named Collect but the routes still mount under /claim/*. The route rename is upcoming tech-debt; the URL contract is stable.

​
Create a request

curl -X POST https://api.getovra.com/claim/requests \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationWalletId": "wal_...",
    "amountEuros": 49.00,
    "description": "Research report — 3 sources",
    "payerEmail": "ops@acme.example"
  }'
Response: 
{
  "id": "pr_...",
  "amountEuros": 49,
  "status": "pending",
  "settlementType": "external",
  "sepaInstructions": {
    "iban": "DE89370400440000001234",
    "bic": "PLINDE21",
    "reference": "OVRA-PR-a3f9b1c2"
  },
  "expiresAt": "2026-05-20T10:00:00Z"
}

​
Settle path matrix

Counterparty has an Ovra wallet. Pass counterpartyOwnerId in the create call. The counterparty calls POST /claim/requests/:id/settle with sourceWalletId. We run the debit and credit in a single transaction:
  • SQL BEGIN
  • UPDATE wallets SET balance_euros = balance_euros - amount WHERE id = :src AND balance_euros >= amount
  • UPDATE wallets SET balance_euros = balance_euros + amount WHERE id = :dst
  • INSERT ledger_entries (debit + credit), transfers row, mark request paid
  • COMMIT
  • Fire claim.request.paid webhook
Result: instant, free, fully auditable. ✅ Production-ready.

​
Surfaces

SurfaceStatus
REST APIFull
SDK (@ovra/sdk)ovra.collect.*
MCPovra_claim (action-multiplexed) — tool name will rename to ovra_collect in a future MCP release
Dashboard/dashboard/collect — create drawer, filter list, detail drawer

​
Webhooks

Subscribe to these events to react in real time:
  • claim.request.created
  • claim.request.paid
  • claim.request.expired
  • claim.request.cancelled
See Webhooks for delivery, retries, and signature verification.

​
Next

Accounts

Wallets, IBANs, transfers — where the funds live.

Webhooks

Fire-and-forget delivery for claim.request.* events.