> For the complete documentation index, see [llms.txt](https://docs.creditcoop.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.creditcoop.xyz/developer-api-docs/borrowers.md). # Borrowers Borrower management ## List borrowers > List enabled borrower organizations. Authentication is optional but affects results. ```json {"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Borrowers","description":"Borrower management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]},{}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"Organization":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid","description":"Organization unique identifier"},"name":{"type":"string","maxLength":255,"description":"Organization display name"},"slug":{"type":"string","maxLength":100,"description":"URL-friendly identifier"},"header":{"type":"string","nullable":true,"description":"Short tagline or headline for the organization profile"},"description":{"type":"string","nullable":true,"description":"Brief summary of the organization"},"overview":{"type":"string","nullable":true,"description":"Long-form organization description (may contain Markdown)"},"links":{"type":"array","description":"Organization links and image assets. Labels starting with \"#\" are image assets (e.g. \"#logo\", \"#header\"); all others are external links (e.g. \"Twitter\", \"Website\").","items":{"type":"object","required":["id","label","url"],"properties":{"id":{"type":"string","format":"uuid","description":"Link unique identifier"},"label":{"type":"string","description":"Link type. \"#logo\" and \"#header\" denote image assets; other values (e.g. \"Twitter\", \"Website\") denote external links."},"linkText":{"type":"string","nullable":true,"description":"Display text for external links (e.g. \"@raincards\", \"rain.xyz\")"},"iconUrl":{"type":"string","nullable":true,"description":"Icon image URL for external links"},"url":{"type":"string","description":"Target URL (image URL for asset links, destination URL for external links)"}}}}}},"Pagination":{"type":"object","required":["total","limit","offset"],"properties":{"total":{"type":"integer","description":"Total number of records matching the query"},"limit":{"type":"integer","description":"Maximum number of records returned per page"},"offset":{"type":"integer","description":"Number of records skipped from the start"}}}}},"paths":{"/v3/borrowers":{"get":{"operationId":"listBorrowers","summary":"List borrowers","tags":["Borrowers"],"description":"List enabled borrower organizations. Authentication is optional but affects results.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["organization","stats","apy","status"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"organization\" (includes full organization object with links), \"stats\" (includes borrower statistics), \"apy\" (includes weighted APY and facilities count), \"status\" (includes on-chain cross-default status, one entry per Servicing contract)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["borrowers","pagination"],"properties":{"borrowers":{"type":"array","items":{"type":"object","required":["organizationId","name","networkIds"],"properties":{"organizationId":{"type":"string","format":"uuid","description":"Borrower organization ID"},"name":{"type":"string","description":"Organization name"},"networkIds":{"type":"array","items":{"type":"string"},"description":"CAIP-2 network identifiers for blockchain networks this borrower has credit facilities on"},"organization":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Organization"}],"description":"Full organization details with links. Only included when expand includes \"organization\"."},"stats":{"type":"object","nullable":true,"description":"Borrower statistics. Only included when expand includes \"stats\".","required":["totalVolumeUsd","activeLoansUsd","totalInterestPaidUsd","totalBorrowedUsd"],"properties":{"totalVolumeUsd":{"type":"string","description":"Total USD volume (borrows + all repayments)"},"activeLoansUsd":{"type":"string","description":"Current outstanding principal in USD (borrows - principal repayments)"},"totalInterestPaidUsd":{"type":"string","description":"Cumulative interest paid in USD"},"totalBorrowedUsd":{"type":"string","description":"Cumulative amount borrowed in USD (regardless of repayments)"}}},"apy":{"type":"object","nullable":true,"description":"APY and facilities data. Only included when expand includes \"apy\".","required":["facilitiesCount","activeCreditLinesCount"],"properties":{"weightedApyPct":{"type":"number","nullable":true,"description":"Weighted average APY as a percentage (e.g., 8.5 = 8.5%). Null if no credit facility or rates unavailable."},"facilitiesCount":{"type":"number","description":"Number of credit facilities for this borrower."},"activeCreditLinesCount":{"type":"number","description":"Number of open credit lines across all credit facilities for this borrower."}}},"status":{"type":"object","nullable":true,"description":"On-chain cross-default status. Only included when expand includes \"status\". Returns one entry per Servicing contract — each is an independent cross-default group, so they are not merged into a single status.","required":["servicings"],"properties":{"servicings":{"type":"array","items":{"type":"object","required":["address","networkId","closed","isDefaulted","breachLevel","covenants"],"properties":{"address":{"type":"string","description":"Servicing contract address"},"networkId":{"type":"string","nullable":true,"description":"CAIP-2 network identifier (e.g. eip155:8453)"},"closed":{"type":"boolean","nullable":true,"description":"Whether the relationship has been wound down or liquidated. Null when unavailable."},"isDefaulted":{"type":"boolean","nullable":true,"description":"Whether the borrower is in cross-default (applies to every facility under this Servicing). Null when unavailable."},"breachLevel":{"type":"string","nullable":true,"enum":["NONE","CURING","DEFAULTED"],"description":"Worst covenant breach level. CURING is a curable breach within its cure window. Null when it cannot be determined."},"covenants":{"type":"array","items":{"type":"object","required":["address","level"],"properties":{"address":{"type":"string","description":"Covenant contract address"},"level":{"type":"string","nullable":true,"enum":["NONE","CURING","DEFAULTED"],"description":"Breach level for this covenant. Null when its read failed."}}}}}}}}}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}}}} ``` ## Get borrower by ID > Get a single borrower organization by ID. Authentication is optional but required to view private borrowers. ```json {"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Borrowers","description":"Borrower management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]},{}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"Organization":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid","description":"Organization unique identifier"},"name":{"type":"string","maxLength":255,"description":"Organization display name"},"slug":{"type":"string","maxLength":100,"description":"URL-friendly identifier"},"header":{"type":"string","nullable":true,"description":"Short tagline or headline for the organization profile"},"description":{"type":"string","nullable":true,"description":"Brief summary of the organization"},"overview":{"type":"string","nullable":true,"description":"Long-form organization description (may contain Markdown)"},"links":{"type":"array","description":"Organization links and image assets. Labels starting with \"#\" are image assets (e.g. \"#logo\", \"#header\"); all others are external links (e.g. \"Twitter\", \"Website\").","items":{"type":"object","required":["id","label","url"],"properties":{"id":{"type":"string","format":"uuid","description":"Link unique identifier"},"label":{"type":"string","description":"Link type. \"#logo\" and \"#header\" denote image assets; other values (e.g. \"Twitter\", \"Website\") denote external links."},"linkText":{"type":"string","nullable":true,"description":"Display text for external links (e.g. \"@raincards\", \"rain.xyz\")"},"iconUrl":{"type":"string","nullable":true,"description":"Icon image URL for external links"},"url":{"type":"string","description":"Target URL (image URL for asset links, destination URL for external links)"}}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/borrowers/{id}":{"get":{"operationId":"getBorrower","summary":"Get borrower by ID","tags":["Borrowers"],"description":"Get a single borrower organization by ID. Authentication is optional but required to view private borrowers.","parameters":[{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["organization","stats","apy","status"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"organization\" (includes full organization object with links), \"stats\" (includes borrower statistics), \"apy\" (includes weighted APY and facilities count), \"status\" (includes on-chain cross-default status, one entry per Servicing contract)."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Borrower organization ID. Example: 550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["organizationId","name","networkIds"],"properties":{"organizationId":{"type":"string","format":"uuid","description":"Borrower organization ID"},"name":{"type":"string","description":"Organization name"},"networkIds":{"type":"array","items":{"type":"string"},"description":"CAIP-2 network identifiers for blockchain networks this borrower has credit facilities on"},"organization":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Organization"}],"description":"Full organization details with links. Only included when expand includes \"organization\"."},"stats":{"type":"object","nullable":true,"description":"Borrower statistics. Only included when expand includes \"stats\".","required":["totalVolumeUsd","activeLoansUsd","totalInterestPaidUsd","totalBorrowedUsd"],"properties":{"totalVolumeUsd":{"type":"string","description":"Total USD volume (borrows + all repayments)"},"activeLoansUsd":{"type":"string","description":"Current outstanding principal in USD (borrows - principal repayments)"},"totalInterestPaidUsd":{"type":"string","description":"Cumulative interest paid in USD"},"totalBorrowedUsd":{"type":"string","description":"Cumulative amount borrowed in USD (regardless of repayments)"}}},"apy":{"type":"object","nullable":true,"description":"APY and facilities data. Only included when expand includes \"apy\".","required":["facilitiesCount","activeCreditLinesCount"],"properties":{"weightedApyPct":{"type":"number","nullable":true,"description":"Weighted average APY as a percentage (e.g., 8.5 = 8.5%). Null if no credit facility or rates unavailable."},"facilitiesCount":{"type":"number","description":"Number of credit facilities for this borrower."},"activeCreditLinesCount":{"type":"number","description":"Number of open credit lines across all credit facilities for this borrower."}}},"status":{"type":"object","nullable":true,"description":"On-chain cross-default status. Only included when expand includes \"status\". Returns one entry per Servicing contract — each is an independent cross-default group, so they are not merged into a single status.","required":["servicings"],"properties":{"servicings":{"type":"array","items":{"type":"object","required":["address","networkId","closed","isDefaulted","breachLevel","covenants"],"properties":{"address":{"type":"string","description":"Servicing contract address"},"networkId":{"type":"string","nullable":true,"description":"CAIP-2 network identifier (e.g. eip155:8453)"},"closed":{"type":"boolean","nullable":true,"description":"Whether the relationship has been wound down or liquidated. Null when unavailable."},"isDefaulted":{"type":"boolean","nullable":true,"description":"Whether the borrower is in cross-default (applies to every facility under this Servicing). Null when unavailable."},"breachLevel":{"type":"string","nullable":true,"enum":["NONE","CURING","DEFAULTED"],"description":"Worst covenant breach level. CURING is a curable breach within its cure window. Null when it cannot be determined."},"covenants":{"type":"array","items":{"type":"object","required":["address","level"],"properties":{"address":{"type":"string","description":"Covenant contract address"},"level":{"type":"string","nullable":true,"enum":["NONE","CURING","DEFAULTED"],"description":"Breach level for this covenant. Null when its read failed."}}}}}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Get borrower activity logs > Get on-chain activity logs for a borrower. Works for both v2 and v3 borrowers, and contains two kinds of events:\ > \- \*\*Financing events\*\* — borrows/draws, repayments, deposits, withdrawals, fees, and (v3) interest accruals, emitted by the borrower's credit facilities.\ > \- \*\*Status events\*\* (v3 only) — covenant, collateral, and servicing changes.\ > \ > Each item carries a \`source\` (\`facility\`, \`servicing\`, \`covenant\`, or \`collateral\`) indicating which contract emitted it, and \`lineTokenId\` identifying the individual credit line (position) where applicable.\ > \ > Supports three response formats via the \`format\` query parameter:\ > \- \*\*json\*\* (default) — paginated JSON (default limit 20, max 1000).\ > \- \*\*csv\*\* — streamed CSV file download (up to 1 000 000 rows).\ > \- \*\*event-stream\*\* — Server-Sent Events stream (up to 1 000 000 rows). Each log is emitted as a named \`log\` event with JSON data. A final \`done\` event carries \`{"total": N}\`. Connect with \`EventSource\` or \`fetch\`:\ > \ > \`\`\`js\ > const es = new EventSource('/v3/borrowers/{id}/logs?format=event-stream', {\ > headers: { 'x-api-key': 'cc\_...' },\ > });\ > es.addEventListener('log', (e) => console.log(JSON.parse(e.data)));\ > es.addEventListener('done', (e) => { console.log('total:', JSON.parse(e.data).total); es.close(); });\ > \`\`\`\ > \ > Event types: AddCredit, RepayPrincipal, RepayInterest, IncreaseCredit, ReservesChanged, Borrow, WithdrawDeposit, WithdrawProfit, PayServicingFee, TransferOriginationFee, Originated, CommitmentDrawn, CommitmentRepaid, CommitmentClaimed, CommitmentAccrued, CommitmentClosed, Refinanced, SurplusClaimed, CloseSurplusRecorded, Closed, CovenantAdded, CovenantRemoved, CovenantEvalFailed, CollateralAdded, CollateralRemoved, AdvanceRateUpdated, CollateralReleased, CollateralReleaseFailed, FacilityAdded, FacilityRemoved, FacilityClosed, FacilityCloseFailed, TrusteeSet, Liquidated, ServicingClosed, BreachDeclared, BreachCured, Checkpointed, Attested, Released, ReleaseFailed, TargetAdded, TargetRemoved, Claimed, OwnerWithdrawn, OperatorUpdated, Operated, TargetReleased, TargetReleaseFailed. ````json {"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Borrowers","description":"Borrower management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"Pagination":{"type":"object","required":["total","limit","offset"],"properties":{"total":{"type":"integer","description":"Total number of records matching the query"},"limit":{"type":"integer","description":"Maximum number of records returned per page"},"offset":{"type":"integer","description":"Number of records skipped from the start"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/borrowers/{id}/logs":{"get":{"operationId":"getBorrowerLogs","summary":"Get borrower activity logs","tags":["Borrowers"],"description":"Get on-chain activity logs for a borrower. Works for both v2 and v3 borrowers, and contains two kinds of events:\n- **Financing events** — borrows/draws, repayments, deposits, withdrawals, fees, and (v3) interest accruals, emitted by the borrower's credit facilities.\n- **Status events** (v3 only) — covenant, collateral, and servicing changes.\n\nEach item carries a `source` (`facility`, `servicing`, `covenant`, or `collateral`) indicating which contract emitted it, and `lineTokenId` identifying the individual credit line (position) where applicable.\n\nSupports three response formats via the `format` query parameter:\n- **json** (default) — paginated JSON (default limit 20, max 1000).\n- **csv** — streamed CSV file download (up to 1 000 000 rows).\n- **event-stream** — Server-Sent Events stream (up to 1 000 000 rows). Each log is emitted as a named `log` event with JSON data. A final `done` event carries `{\"total\": N}`. Connect with `EventSource` or `fetch`:\n\n```js\nconst es = new EventSource('/v3/borrowers/{id}/logs?format=event-stream', {\n headers: { 'x-api-key': 'cc_...' },\n});\nes.addEventListener('log', (e) => console.log(JSON.parse(e.data)));\nes.addEventListener('done', (e) => { console.log('total:', JSON.parse(e.data).total); es.close(); });\n```\n\nEvent types: AddCredit, RepayPrincipal, RepayInterest, IncreaseCredit, ReservesChanged, Borrow, WithdrawDeposit, WithdrawProfit, PayServicingFee, TransferOriginationFee, Originated, CommitmentDrawn, CommitmentRepaid, CommitmentClaimed, CommitmentAccrued, CommitmentClosed, Refinanced, SurplusClaimed, CloseSurplusRecorded, Closed, CovenantAdded, CovenantRemoved, CovenantEvalFailed, CollateralAdded, CollateralRemoved, AdvanceRateUpdated, CollateralReleased, CollateralReleaseFailed, FacilityAdded, FacilityRemoved, FacilityClosed, FacilityCloseFailed, TrusteeSet, Liquidated, ServicingClosed, BreachDeclared, BreachCured, Checkpointed, Attested, Released, ReleaseFailed, TargetAdded, TargetRemoved, Claimed, OwnerWithdrawn, OperatorUpdated, Operated, TargetReleased, TargetReleaseFailed.","parameters":[{"schema":{"type":"string","enum":["json","csv","event-stream"],"default":"json"},"in":"query","name":"format","required":false,"description":"Response format. \"json\" returns paginated JSON (default 20, max 1000). \"csv\" returns a streamed CSV file download. \"event-stream\" returns Server-Sent Events with each log as a named \"log\" event and a final \"done\" event. Event types: AddCredit, RepayPrincipal, RepayInterest, IncreaseCredit, ReservesChanged, Borrow, WithdrawDeposit, WithdrawProfit, PayServicingFee, TransferOriginationFee, Originated, CommitmentDrawn, CommitmentRepaid, CommitmentClaimed, CommitmentAccrued, CommitmentClosed, Refinanced, SurplusClaimed, CloseSurplusRecorded, Closed, CovenantAdded, CovenantRemoved, CovenantEvalFailed, CollateralAdded, CollateralRemoved, AdvanceRateUpdated, CollateralReleased, CollateralReleaseFailed, FacilityAdded, FacilityRemoved, FacilityClosed, FacilityCloseFailed, TrusteeSet, Liquidated, ServicingClosed, BreachDeclared, BreachCured, Checkpointed, Attested, Released, ReleaseFailed, TargetAdded, TargetRemoved, Claimed, OwnerWithdrawn, OperatorUpdated, Operated, TargetReleased, TargetReleaseFailed."},{"schema":{"type":"string"},"in":"query","name":"networkId","required":false,"description":"Filter logs by CAIP-2 network identifier. Example: eip155:8453"},{"schema":{"type":"string","format":"date"},"in":"query","name":"startDate","required":false,"description":"Start date (YYYY-MM-DD). Example: 2025-01-15"},{"schema":{"type":"string","format":"date"},"in":"query","name":"endDate","required":false,"description":"End date, inclusive (YYYY-MM-DD). Example: 2025-01-15"},{"schema":{"type":"integer","minimum":1},"in":"query","name":"limit","required":false,"description":"Maximum number of results. For json: default 20, max 1000. For csv/event-stream: default 1000000, max 1000000."},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Borrower organization ID. Example: 550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Borrower activity logs — financing events from the borrower's credit facilities (v2 and v3), plus v3 covenant/collateral/servicing status events. Response format depends on the `format` query parameter.","content":{"application/json":{"schema":{"type":"object","required":["organizationId","logs","pagination"],"properties":{"organizationId":{"type":"string","format":"uuid","description":"Borrower organization ID"},"logs":{"type":"array","items":{"type":"object","required":["timestamp","eventType","direction","amount","decimals","token","lineTokenId","address","source","contractAddress","networkId","txHash"],"properties":{"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string","description":"Event type. One of: AddCredit, RepayPrincipal, RepayInterest, IncreaseCredit, ReservesChanged, Borrow, WithdrawDeposit, WithdrawProfit, PayServicingFee, TransferOriginationFee, Originated, CommitmentDrawn, CommitmentRepaid, CommitmentClaimed, CommitmentAccrued, CommitmentClosed, Refinanced, SurplusClaimed, CloseSurplusRecorded, Closed, CovenantAdded, CovenantRemoved, CovenantEvalFailed, CollateralAdded, CollateralRemoved, AdvanceRateUpdated, CollateralReleased, CollateralReleaseFailed, FacilityAdded, FacilityRemoved, FacilityClosed, FacilityCloseFailed, TrusteeSet, Liquidated, ServicingClosed, BreachDeclared, BreachCured, Checkpointed, Attested, Released, ReleaseFailed, TargetAdded, TargetRemoved, Claimed, OwnerWithdrawn, OperatorUpdated, Operated, TargetReleased, TargetReleaseFailed"},"direction":{"type":"string","enum":["in","out","none"],"description":"Cash flow direction: in (deposits/repayments), out (borrows/withdrawals/fees), none (not a facility cash flow — e.g. status/lifecycle events, interest accruals, or collateral adapter sweeps/withdrawals; these may still carry a meaningful amount)"},"amount":{"type":"string","description":"Raw on-chain amount (smallest unit integer string)"},"decimals":{"type":"integer","nullable":true,"description":"Token decimals for converting amount to human-readable form"},"token":{"type":"string","nullable":true,"description":"Token contract address"},"lineTokenId":{"type":"string","nullable":true,"description":"Credit line / commitment token ID"},"address":{"type":"string","nullable":true,"description":"The address a status event concerns (e.g. the covenant, collateral, trustee, or counterparty); null when not applicable."},"source":{"type":"string","enum":["facility","servicing","covenant","collateral"],"description":"The kind of contract that emitted the event. `facility` is the lending contract (financing events, for both v2 and v3); `servicing`, `covenant`, and `collateral` are v3 status events. The individual credit line (position) is given by `lineTokenId`."},"contractAddress":{"type":"string"},"networkId":{"type":"string","description":"CAIP-2 network identifier (e.g. eip155:8453)"},"txHash":{"type":"string"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}},"text/csv":{"schema":{"type":"string","description":"CSV file download. Columns: timestamp, eventType, direction, amount, decimals, token, lineTokenId, contractAddress, networkId, txHash, source, address."}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream. Each log is emitted as a named \"log\" event with JSON data. A final \"done\" event carries {\"total\": N}."}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` ## Get borrower analytics time series > Get analytics time series for a borrower. Returns daily cashflow, trailing sums, and debt metrics. Auto-detects loan start date from the first borrow event if startDate is not provided. ```json {"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Borrowers","description":"Borrower management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/borrowers/{id}/analytics":{"get":{"operationId":"getBorrowerAnalytics","summary":"Get borrower analytics time series","tags":["Borrowers"],"description":"Get analytics time series for a borrower. Returns daily cashflow, trailing sums, and debt metrics. Auto-detects loan start date from the first borrow event if startDate is not provided.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"startDate","required":false,"description":"Start date (YYYY-MM-DD). Defaults to auto-detected loan start."},{"schema":{"type":"string","format":"date"},"in":"query","name":"endDate","required":false,"description":"End date, inclusive (YYYY-MM-DD). Defaults to today."},{"schema":{"type":"string"},"in":"query","name":"trailingDays","required":false,"description":"Comma-separated trailing periods in days (e.g. \"14,30,120\"). Max: 365. Defaults to org config or \"30\"."},{"schema":{"type":"string"},"in":"query","name":"stages","required":false,"description":"Comma-separated INTERNAL (on-chain) stage filter for cashflow (e.g. \"secured,settled\"). Valid values: in_transit, secured, settled. \"external\" is also accepted for backward compatibility but is ignored here — it does not error and does not affect the internal series; external-business cashflow is a separate series (see externalEntryType / cashFlowDailyExternal). Normally you do not need to specify this parameter. Defaults to org config or \"secured\"."},{"schema":{"type":"string","enum":["inflow","net"]},"in":"query","name":"direction","required":false,"description":"Internal (on-chain) cash flow direction. \"inflow\" counts only inflows. \"net\" computes net flow (inflows - outflows). Defaults to org config or \"inflow\"."},{"schema":{"type":"string","enum":["transfer","daily_cashflow"]},"in":"query","name":"externalEntryType","required":false,"description":"Which external-business source to display: \"transfer\" (individual transactions) or \"daily_cashflow\" (daily aggregates). Defaults to whichever source has data."},{"schema":{"type":"string","enum":["inflow","net"]},"in":"query","name":"externalDirection","required":false,"description":"External-business cash flow direction, independent of the internal direction. Defaults to org config or \"inflow\"."},{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["debt"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"debt\" (adds live on-chain debt state)."},{"schema":{"type":"string","enum":["json","csv"],"default":"json"},"in":"query","name":"format","required":false,"description":"Response format. \"json\" (default) or \"csv\" file download."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Borrower organization ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["organizationId","organizationName","config","timeSeries","meta"],"properties":{"organizationId":{"type":"string","format":"uuid"},"organizationName":{"type":"string"},"config":{"type":"object","properties":{"trailingPeriods":{"type":"array","items":{"type":"integer"}},"stages":{"type":"array","items":{"type":"string"},"description":"Internal (on-chain) stages included"},"direction":{"type":"string","enum":["inflow","net"],"description":"Internal direction"},"externalEntryType":{"type":"string","enum":["transfer","daily_cashflow"],"description":"External source displayed (resolved — may have been auto-picked)"},"externalDirection":{"type":"string","enum":["inflow","net"],"description":"External direction"},"loanStartDate":{"type":"string","nullable":true},"loanEndDate":{"type":"string","nullable":true},"loanTermDays":{"type":"integer","nullable":true,"description":"Loan term in days (loanEndDate - loanStartDate), used as trailing period for SRR/WALD"}}},"timeSeries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"cashFlowDaily":{"type":"string","description":"Internal (on-chain) daily cashflow for the selected pipeline stages"},"trailingCashFlows":{"type":"object","additionalProperties":{"type":"string"},"description":"Internal trailing cashflow sums keyed by period (e.g. { \"14\": \"423000.00\", \"30\": \"1523450.00\" })"},"cashFlowDailyExternal":{"type":"string","nullable":true,"description":"External-business daily cashflow (money moving outside the on-chain pipeline). Null when the org has no external-business cashflow in range (see meta.hasExternalCashflow)."},"trailingCashFlowsExternal":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"External-business trailing cashflow sums keyed by period (e.g. { \"14\": \"423000.00\", \"30\": \"1523450.00\" }). Null when the org has no external-business cashflow in range (see meta.hasExternalCashflow)."},"principal":{"type":"string"},"interestPaid":{"type":"string"},"debt":{"type":"string"},"creditLimit":{"type":"string","nullable":true,"description":"Reconstructed credit limit (sum of AddCredit deposits) as of this date"},"loanTerm":{"type":"string","nullable":true,"description":"Deposit-weighted average loan term (days) of credit lines open on this date"},"dscr":{"type":"string","nullable":true,"description":"DSCR: loan-term-windowed cashflow / credit limit"},"srr":{"type":"string","nullable":true,"description":"SRR (Spigot Repayment Rate): 30d trailing cashflow / credit limit"},"wald":{"type":"string","nullable":true,"description":"WALD (Weighted Avg Liquidity Duration): 30 / SRR (days to repay at current 30d rate)"},"collateral":{"type":"string","nullable":true,"description":"Cumulative collateral snapshot (USD) as of this date"}}}},"currentDebt":{"type":"object","nullable":true,"description":"Live on-chain debt state. Only present when expand=debt.","properties":{"principal":{"type":"string"},"accruedInterest":{"type":"string"},"deposit":{"type":"string"},"totalDebt":{"type":"string"},"facilities":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"networkId":{"type":"string"},"principal":{"type":"string"},"deposit":{"type":"string"},"interestAccrued":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"dataRange":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"entriesCount":{"type":"integer"},"loanStartDetected":{"type":"boolean"},"hasExternalCashflow":{"type":"boolean","description":"Whether the org has any external-business cashflow in range, in either source (drives whether external figures are shown)"},"externalSourcesAvailable":{"type":"array","items":{"type":"string","enum":["transfer","daily_cashflow"]},"description":"Which external sources hold data in range — the meaningful options for the external source selector"},"externalCashflowLabel":{"type":"string","nullable":true,"description":"Optional display label for the external cashflow series (e.g. 'Borrower Reported'). Null when no label has been set."}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.creditcoop.xyz/developer-api-docs/borrowers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.