SPCR Documentation
Using SPCR

The SPCR API

Originators, funders and servicers can connect their own systems to their SPCR workspace, and do through code what they otherwise do on the website: register receivables, sell pools, follow their status and check a loan tape.

What it covers

Originators can create pools, register receivables into them, sell a pool to a funder, and read their pools, receivables and sales.

Funders can read the pools they hold, sell a pool on to another funder, and follow those sales.

Both can check who holds a receivable, as on the verification site.

Servicers can check a fund's loan tape against the registry, as on the servicer workspace's Tape check page, for one fund they service per key.

The API applies exactly the same rules as the website. A Loan ID registered anywhere before is refused, a pool is sold whole, and an originator sees who it sold to, not who holds a pool afterwards.

Getting access

The API is available to workspaces only. Keys are created in your workspace, under API in the menu, by a signed-in member. Every request needs one.

  1. Open your workspace and choose API.
  2. Create a key: give it a name, choose its permissions, and choose when it expires.
  3. Copy the key when it is shown. SPCR keeps only a fingerprint of it, so it cannot be shown again. Store it as you would a password.

On a live workspace, creating a key asks for your password again, as a sale does. A key can act for the workspace without anyone present.

Permissions

Each key carries only the permissions chosen when it was created.

  • Read: pools, receivables, sales and verification.
  • Register: create pools and register receivables. Originators only.
  • Sell: start pool sales. A sale cannot be undone once it begins to land on chain, so this permission is never given by default.
  • Check: check tape rows against the registry. Servicers only. A check key is tied to one fund chosen when it is created, can ask about no other, and lasts at most 90 days. It reads and changes nothing.

Reference

Base address https://spcr.io/api/v1. Send the key in every request as Authorization: Bearer <key>. Bodies and answers are JSON. A key acts as its own workspace only, with the permissions chosen when it was created, and the same rules as the website apply: nothing a key does could not be done on the website by a member.

Request Permission What it does
GET /pools read Originators: your pools, with status and who each was sold to. Funders: the pools you hold receivables in.
POST /pools register Originators only. Create a pool: code, name, accessCode, and optionally representation and trancheName.
GET /pools/{poolId}/receivables read Originators: a pool's receivables, with Loan ID, receivable ID, status, held in or sold to, registration date and transaction. Funders: your receivables in that pool.
GET /portfolio read Funders only. Your whole vault in one call: every pool you hold receivables in, and each receivable you hold there with its Loan ID, receivable ID, token ID, registration date and transaction.
POST /registrations register Originators only. Register receivables: { poolId, loanIds: [...] }. A verdict per Loan ID; a Loan ID registered anywhere before is refused.
GET /funders read Funders a pool can be sold to: name and vault address.
POST /sales sell Sell a whole pool: { poolId, funderAddress }. Returns a sale ID at once; the sale runs in the background.
GET /sales/{saleId} read A sale's progress. With the sell permission, each call also sends its next batches.
GET /verify/{receivableId} read Who holds a receivable and its history. The receivable ID is SHA-256(Loan ID | pool access code), computed on your side.
POST /servicer/check check Servicers only. Check up to 500 receivables for the key's fund: { tokenIds: [...] }, each a receivable ID computed on your side. Returns per receivable a status, whether you have confirmed it, and a date (registered or last moved).

Tape check statuses

status Meaning
this-fund Registered to this fund.
clear Registered and in STOKR custody, not yet with this fund.
conflict Registered to another holder. Not named: that is the other fund's business.
sold Was with this fund and has since moved out of it.
not-registered Not on the registry.

Example

curl https://spcr.io/api/v1/pools \
  -H "Authorization: Bearer $SPCR_API_KEY"

Limits and errors

  • 120 requests a minute per workspace, across all its keys.
  • A registration takes up to 1,500 Loan IDs per request on Stellar, 5,000 on Ethereum.
  • A registration answers per Loan ID. A refused row says why. A row refused because the network turned the transaction away, or because the request ran out of time ("not attempted"), had nothing written and can be sent again.
  • Checking receivables (/verify and /servicer/check) counts against an hourly allowance of receivable IDs, shared with the verification site.
  • Errors come back as { "error": "..." } with the usual HTTP status: 401 for a missing, revoked or expired key, 403 for a missing permission, 429 when over the limit.

Keeping keys safe

  • Use a separate key for each system, so one can be revoked without affecting the others.
  • Give each key only the permissions it needs, and an expiry.
  • Revoke a key in your workspace the moment it may have been exposed. It stops working on its next request.

Privacy

The API stores nothing the website does not. Registration sends only Loan IDs. To check a receivable, you send its receivable ID, the fingerprint of the Loan ID and pool access code, computed on your side, so neither the Loan ID nor the access code leaves your systems.