Bridge
A bridge registers an external service and manages connectivity to it, storing the service's base URL, authentication credentials, and communication settings.
Bridges can participate in two flows. For payment processing, the ledger calls the bridge to coordinate balance movements through a two-phase commit protocol, ensuring both sides stay in sync. Through effects, the bridge receives notifications when ledger data changes, enabling integrations like fraud monitoring, analytics, and data synchronization.
Each bridge declares which flows it participates in through traits, such as debits, credits, or effects, and can filter which operations it handles.
To participate in payment processing, the bridge must be assigned to a wallet. To receive event notifications, an effect must be configured to route events to it.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /bridges | Register a remote service as a bridge that can receive ledger events. |
| GET | /bridges | Query bridges with filtering, sorting, and pagination. |
| GET | /bridges/{id} | Retrieve a bridge by its handle or LUID. |
| PUT | /bridges/{id} | Submit a new version of a bridge. |
| DELETE | /bridges/{id} | Permanently remove a bridge from the ledger. |
| POST | /bridges/{id}/proofs | Submit a signed proof to a bridge record. |
Actions
| Method | Path | Description |
|---|---|---|
| POST | /bridges/{id}/activate | Retry failed or pending event deliveries for a bridge. |
| POST | /bridges/{id}/events/retry | Retry failed or pending event deliveries for a bridge. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /bridges/{id}/access/!check | Evaluate what actions a signer can perform on this bridge. |
| GET | /bridges/{id}/changes | Retrieve the change history of a bridge by its handle or LUID. |
| GET | /bridges/{id}/changes/{change} | Retrieve a change record for a bridge by handle or LUID and change number. |
Trait Filters
The debits, credits, statuses, and anchors traits support filters using MongoDB-style query syntax to limit which requests the bridge receives. For debit and credit traits, filters apply only to the prepare phase — commit and abort requests are always delivered.
Debit and Credit Filters
Match on bridge entry fields sent during payment processing:
symbol.handle— symbolsource.handle— source addresstarget.handle— target addressamount— transfer amountintent.data.*— any intent field includinghandle,schema, andcustom
Status Filters
Match on the full intent record sent during status updates:
claims.action— claim typeclaims.source.handle— source addressclaims.target.handle— target addressclaims.symbol.handle— symbolmeta.status— intent status
Anchor Filters
Match on anchor fields sent during anchor operations:
target— target addresssource— source addresssymbol— symbolhandle— anchor handleamount— anchor amount
Related
- About Bridges — how bridges connect the ledger to external systems
- Build a Bridge — step-by-step bridge implementation guide
- Extending Ledger — the broader integration model
Create access token POST
Creates an access token by exchanging OAuth 2.0 client credentials, following RFC 6749 Section 4.4 (Client Credentials Grant). **Authentication:** Provide credentials via HTTP Basic Auth (`Authorization: Basic base64(client_id:client_secret)`) or as `client_id` and `client_secret` form parameters in the request body. **Response:** Returns a signed JWT (RS256) that can be used as a Bearer token for API access. Use the `kid` header in the JWT to look up the corresponding public key from the provider signer's `key-pair` factor for verification. **Note:** This endpoint follows the RFC 6749 standard. It accepts `application/x-www-form-urlencoded` bodies, returns an RFC 6749 token response, and uses standard error codes (`invalid_client`, `invalid_request`, etc.).
Create bridge POST
A bridge declares a remote service and the capabilities it supports through traits: `debits`, `credits`, `statuses`, `anchors`, `domains`, and `effects`. Traits can include filters to limit which requests the bridge receives. See [Trait Filters](/ledger/reference/api/bridge#trait-filters) for available filter fields per trait. To participate in payment processing, the bridge must be assigned to a wallet. To receive event notifications, an effect must be configured to route events to it. Security rules define how outbound requests are authenticated — either OAuth 2.0 client credentials or custom headers. Broadcasts the `bridge-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.