# Get a loan

Source: https://business-api-docs.youhodler.com/api/reference/loans/loans-get

**Authentication:** Send `Authorization: Bearer <access_token>`.

Returns the caller's loan: its current debt split, its latest valuation and its obligations. The loans.read grant must cover the loan borrower account; otherwise the service returns 403.

## Parameters

| Name | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `loan_id` | path | string | Yes | format: uuid |

## Request

**Request URL — GET**
```http
GET /loans/{loan_id}
```

## Responses

**200 Operation succeeded**

Operation succeeded.

```json
{
  "arrears_since": null,
  "close_reason": null,
  "collateral_amount": {
    "currency": "BTC",
    "value": "2.00000000"
  },
  "collateral_held": {
    "currency": "BTC",
    "value": "2.00000000"
  },
  "created_at": "2026-04-01T00:00:00Z",
  "full_payoff_amount": {
    "currency": "USD",
    "value": "50170.6205"
  },
  "last_ltv": "0.5",
  "last_valued_at": "2026-05-01T10:00:00Z",
  "liquidation_threshold": "0.75",
  "loan_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "margin_call_since": null,
  "margin_call_threshold": "0.6",
  "matures_at": "2027-04-01T00:00:00Z",
  "next_charge_at": "2026-06-01T00:00:00Z",
  "outstanding": {
    "fees": "0",
    "interest": "120.50",
    "penalty_interest": "0",
    "principal": "50000.00"
  },
  "outstanding_total": {
    "currency": "USD",
    "value": "50120.50"
  },
  "price": "50000",
  "price_age_ms": 60000,
  "price_observed_at": "2026-05-01T09:59:00Z",
  "price_source": "internal-index",
  "principal_amount": {
    "currency": "USD",
    "value": "50000.00"
  },
  "status": "active",
  "updated_at": "2026-05-01T10:00:00Z"
}
```

**400 Invalid request payload**

Invalid request payload, query, or parameter shape.

**401 Caller is not authenticated or the bearer token is invalid**

Caller is not authenticated or the bearer token is invalid.

**403 Caller lacks the required capability or permitted scope**

Caller lacks the required capability or permitted scope.

**404 Resource not found**

Resource not found.

**500 An unexpected internal failure occurred**

An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.

**502 Upstream service returned an unexpected error**

Upstream service returned an unexpected error.

**503 Service is temporarily unavailable**

Service is temporarily unavailable; retry with backoff.
### Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `arrears_since` | string or null | Yes |  |
| `close_reason` | "repaid" / "matured" / "ltv_breach" / "offboarding" or null | Yes |  |
| `collateral_amount` | object | Yes | No additional fields |
| `collateral_held` | object | Yes | No additional fields |
| `created_at` | string | Yes | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |
| `full_payoff_amount` | object | Yes | No additional fields |
| `last_ltv` | string or null | Yes |  |
| `last_valued_at` | string or null | Yes |  |
| `liquidation_threshold` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `loan_id` | string | Yes | format: uuid; pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$` |
| `margin_call_since` | string or null | Yes |  |
| `margin_call_threshold` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `matures_at` | string | Yes | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |
| `next_charge_at` | string or null | Yes |  |
| `outstanding` | object | Yes | No additional fields |
| `outstanding_total` | object | Yes | No additional fields |
| `price` | string or null | Yes |  |
| `price_age_ms` | integer or null | Yes |  |
| `price_observed_at` | string or null | Yes |  |
| `price_source` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `status` | "requested" / "awaiting_approval" / "awaiting_compliance" / "active" / "denied" / "origination_failed" / "liquidating" / "liquidation_halted" / "liquidated" / "closed" | Yes |  |
| `updated_at` | string | Yes | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |

Additional fields are not accepted.

##### application/json body.arrears_since

At least one alternative must match.

###### application/json body.arrears_since: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.arrears_since: alternative 2

Type: `null`. 

##### application/json body.close_reason

At least one alternative must match.

###### application/json body.close_reason: alternative 1

Type: `"repaid" / "matured" / "ltv_breach" / "offboarding"`. 

###### application/json body.close_reason: alternative 2

Type: `null`. 

##### application/json body.collateral_amount

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `value` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.collateral_held

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `value` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.full_payoff_amount

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `value` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.last_ltv

At least one alternative must match.

###### application/json body.last_ltv: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.last_ltv: alternative 2

Type: `null`. 

##### application/json body.last_valued_at

At least one alternative must match.

###### application/json body.last_valued_at: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.last_valued_at: alternative 2

Type: `null`. 

##### application/json body.margin_call_since

At least one alternative must match.

###### application/json body.margin_call_since: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.margin_call_since: alternative 2

Type: `null`. 

##### application/json body.next_charge_at

At least one alternative must match.

###### application/json body.next_charge_at: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.next_charge_at: alternative 2

Type: `null`. 

##### application/json body.outstanding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fees` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `interest` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `penalty_interest` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `principal` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.outstanding_total

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `value` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.price

At least one alternative must match.

###### application/json body.price: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.price: alternative 2

Type: `null`. 

##### application/json body.price_age_ms

At least one alternative must match.

###### application/json body.price_age_ms: alternative 1

Type: `integer`. minimum: -9007199254740991; maximum: 9007199254740991

###### application/json body.price_age_ms: alternative 2

Type: `null`. 

##### application/json body.price_observed_at

At least one alternative must match.

###### application/json body.price_observed_at: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.price_observed_at: alternative 2

Type: `null`. 

##### application/json body.price_source

At least one alternative must match.

###### application/json body.price_source: alternative 1

Type: `string`. 

###### application/json body.price_source: alternative 2

Type: `null`. 

##### application/json body.principal_amount

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `value` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

### Response 400 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 401 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object or null | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 403 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 404 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 500 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 502 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).

### Response 503 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).
