ReferenceAPI ReferenceBridge

Create bridge

POST/bridges●Register a remote service as a bridge that can receive ledger events.

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 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 to subscribe.

POST
/bridges

Usage Examples

curl -X POST "http://localhost:3000/v2/bridges" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "a852957e02c3f47aecca687f49b6c4195d00ad7235c1f10be154aa0dff98076a",    "data": {      "handle": "tesla-bank-bridge",      "schema": "rest",      "secure": [],      "custom": {        "description": "Bridge to Tesla Bank API"      },      "config": {        "server": "https://tesla-bank.com/api/v2"      }    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "64d20cdcf09e7a9d7ba6f61889d89fe4249c2fb962731f15d37145420dc44596",          "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",          "result": "kjUtGmvYVDKSdJsb/We56l51LLfYGI5+O5VqdZlu+SnGTJzfVHdC/tjE7VMf1+NjKemG+w/jM1ZJVRmo4qk8BA==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$brg.-01xK2sTuV3eT5xY4",
  "hash": "a852957e02c3f47aecca687f49b6c4195d00ad7235c1f10be154aa0dff98076a",
  "data": {
    "handle": "tesla-bank-bridge",
    "schema": "rest",
    "secure": [],
    "custom": {
      "description": "Bridge to Tesla Bank API"
    },
    "config": {
      "server": "https://tesla-bank.com/api/v2"
    }
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk="
    ],
    "proofs": [
      {
        "signer": "tesla-bank-admin",
        "method": "ed25519-v2",
        "digest": "64d20cdcf09e7a9d7ba6f61889d89fe4249c2fb962731f15d37145420dc44596",
        "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
        "result": "kjUtGmvYVDKSdJsb/We56l51LLfYGI5+O5VqdZlu+SnGTJzfVHdC/tjE7VMf1+NjKemG+w/jM1ZJVRmo4qk8BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "e35f4c68ec4416457d8f09710c23142083299d635bd48f584e6dfd3120784db5",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "Vi92MvGIfzCTbnLxd2d6n/s4SlJBDicVi5yxnvMX5HDw3ahHA4jHkf4dSdZbVp7f2WWTi9uXsd5maoNTUigjBg==",
        "custom": {
          "luid": "$brg.-01xK2sTuV3eT5xY4",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Request Body

application/json

Bridge body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Bridge

Connect external services to process payments and react to ledger changes.

List bridges GET

Use this endpoint to review integration points with external services and network participants. Audit trait configurations, verify security settings, or check bridge statuses. Supported filters: - `data.schema` — bridge schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)