openapi: 3.1.1
info:
  title: Overview
  summary: Originator/Beneficiary entry points
  description: OpenVasp specification v.3.2.1
  x-metadata:
    types:
      - Vasp
    status: alpha
tags:
  - name: Auth
  - name: Identity
  - name: Travel Address
  - name: Transfer
paths:
  /auth/token:
    post:
      summary: Generate JWT access token
      description: >
        Generates a signed, short-lived JWT access token using your API Key.
        This token is required to authenticate all subsequent TRP API requests.
        The endpoint ensures secure client identification and protects access to
        sensitive Travel Rule operations.
      tags:
        - Auth
      responses:
        '200':
          description: JWT token successfully generated.
          content:
            application/json:
              schema: null
              examples:
                default:
                  value:
                    accessToken: eyJhbGciOiJFZERTQSJ9....
                    expiresIn: 3600
                    expiresAt: '2025-11-21T17:04:59.000Z'
                    tokenType: Bearer
          links:
            UseTokenForUserInfo:
              operationId: jwt
              parameters:
                Authorization: $response.body#/accessToken
        '401':
          description: Invalid API key.
  /identity:
    get:
      summary: VASP public info
      description: >
        Retrieves verified information about a VASP based on its Travel Address
        or system identifier. This endpoint is used by VASPs to validate the
        counterparty before executing a Travel Rule transfer.
      tags:
        - Identity
      operationId: identity
      responses:
        '200':
          description: Travel Address generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '400':
          description: Invalid input data.
        '401':
          description: Invalid or expired access token.
    components:
      schemas:
        $ref: ../components/vasp/shemas/identity.yaml
  /travel-address/generate:
    post:
      summary: Generate beneficiary travel address
      description: >-
        Creates a unique, encrypted Travel Address for a beneficiary using
        firstName, lastName, walletAddress and optional externalId. The
        generated Travel Address is used by the originator VASP to initiate a
        compliant Travel Rule transfer.
      tags:
        - Travel Address
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Generate'
            examples:
              default:
                value:
                  operationId: jwt
                  Authorization: 123
                  firstName: John
                  lastName: Snow
                  walletAddress: 1q2w3e4r5t6y7u8i9o0p
                  externalId: user-123456
      responses:
        '200':
          description: Travel Address generated successfully.
          content:
            application/json:
              schema: null
              examples:
                default:
                  value:
                    travelAddress: >-
                      ta4n7WArAHPkQgg3fABMpJiys8AsypD8AqdoXfKBwjH9t5QQbG2uqW9CmQCS3M4GuwxcS6QNdWFUX6nD3tc5bajpNb3svbn87xxy9rCcYNYHN
        '400':
          description: Invalid input data.
        '401':
          description: Invalid or expired access token.
    components:
      Generate:
        operationId: jwt
        type: object
        required:
          - firstName
          - lastName
        properties:
          Authorization:
            type: string
          firstName:
            type: string
            description: First name of the beneficiary.
            example: John
          lastName:
            type: string
            description: Last name of the beneficiary.
            example: Snow
          walletAddress:
            type: string
            description: Wallet address of the beneficiary.
            example: 1q2w3e4r5t6y7u8i9o0p
          externalId:
            type: string
            description: >-
              External identifier of the beneficiary in the originator VASP
              system.
            example: user-123456
  /travel-address/decode:
    post:
      summary: Decode travel address
      description: >
        Decodes a previously generated Travel Address and extracts beneficiary
        metadata (firstName, lastName, walletAddress, externalId). This endpoint
        allows the receiving VASP to retrieve the identity information included
        in the Travel Address before processing a transfer.
      tags:
        - Travel Address
      operationId: decodeTravelAddress
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - travelAddress
              properties:
                travelAddress:
                  type: string
                  description: First name of the beneficiary.
                  example: >-
                    ta4n7WArAHPkQgg3fABMpJiys8AsypD8AqdoXfKBwjH9t5QQbG2uqW9CmQCS3M4GuwxcS6QNdWFUX6nD3tc5bajpNb3svbn87xxy9rCcYNYHN
            examples:
              default:
                value:
                  travelAddress: >-
                    ta4n7WArAHPkQgg3fABMpJiys8AsypD8AqdoXfKBwjH9t5QQbG2uqW9CmQCS3M4GuwxcS6QNdWFUX6nD3tc5bajpNb3svbn87xxy9rCcYNYHN
      responses:
        '200':
          description: Travel Address decode successfully.
          content:
            application/json:
              examples:
                default:
                  value:
                    travelAddress: trp.vasp.com/inquery/1234567890?t=i
        '400':
          description: Invalid input data.
        '401':
          description: Invalid or expired access token.
  /transfers/initiate:
    post:
      tags:
        - Transfer
      summary: Initiate
      description: >
        Initiates a Travel Rule transfer by submitting the full IVMS101
        originator and beneficiary profiles along with the transaction details.
        This endpoint returns a TRP transferId and triggers status callbacks to
        the originator VASP. Required to begin compliant cross-VASPs transfers.
      operationId: initiate
      requestBody:
        content:
          application/json:
            schema:
              required:
                - asset
                - amount
                - callback
                - beneficiary
                - originator
              type: object
              properties:
                travelAddress:
                  type: string
                  maximum: 255
                  minimum: 1
                email:
                  type: string
                  maximum: 255
                txId:
                  type: string
                  maximum: 255
                asset:
                  type: string
                  maximum: 20
                amount:
                  type: string
                  maximum: 50
                callback:
                  type: string
                  pattern: null
                  maximum: 255
                  minimum: 1
                originator:
                  type: object
                  required:
                    - personType
                    - firstName
                    - lastName
                    - dateOfBirth
                  properties:
                    personType:
                      type: string
                    firstName:
                      type: string
                    lastName:
                      type: string
                    dateOfBirth:
                      type: string
                      format: date
                    addressType:
                      type: string
                    streetName:
                      type: string
                    buildingNumber:
                      type: string
                    postCode:
                      type: string
                    townName:
                      type: string
                    country:
                      type: string
                      minLength: 2
                      maxLength: 2
                    nationalId:
                      type: string
                    nationalIdType:
                      type: string
                    accountNumber:
                      type: string
                    walletAddress:
                      type: string
                beneficiary:
                  type: object
                  required:
                    - personType
                    - firstName
                    - lastName
                    - dateOfBirth
                  properties:
                    personType:
                      type: string
                    firstName:
                      type: string
                    lastName:
                      type: string
                    dateOfBirth:
                      type: string
                      format: date
                    addressType:
                      type: string
                    streetName:
                      type: string
                    buildingNumber:
                      type: string
                    postCode:
                      type: string
                    townName:
                      type: string
                    country:
                      type: string
                      minLength: 2
                      maxLength: 2
                    nationalId:
                      type: string
                    nationalIdType:
                      type: string
                    accountNumber:
                      type: string
                    walletAddress:
                      type: string
              example:
                travelAddress: >-
                  taCFLQmuE6GqfR2jRM6m8qF7b9V8PjhzGiED4KmteccXagHRPKVDbLSKe9MwF755NJuKL5Q1CJ1zmXDm2m7crZBUJ7pPfDCoKL1n
                email: ''
                callback: https://webhook.site
                asset: USDT
                amount: 1000
                originator:
                  personType: natural
                  firstName: John
                  lastName: Doe
                  dateOfBirth: 1990-01 15
                  addressType: HOME
                  streetName: Main Street
                  buildingNumber: 123
                  postCode: 10001
                  townName: New York
                  country: US
                  nationalId: 123456789
                  nationalIdType: ARNU
                  accountNumber: ACC123456
                  walletAddress: 00xWE2erfg234234dssdflkjSDFSDF2
                beneficiary:
                  personType: natural
                  firstName: Jane
                  lastName: Smith
                  dateOfBirth: 1985-05 20
                  addressType: HOME
                  streetName: Oak Avenue
                  buildingNumber: 456
                  postCode: 90210
                  townName: Los Angeles
                  country: US
                  accountNumber: ACC789012
                  walletAddress: 0xsldkjflskdjf123lkjl1kj23gjhguttXXC2
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    oneOf:
                      - type: string
                        const: succes
                      - type: string
                        const: false
        '400':
          description: Bad request
        '404':
          description: Validation error
      callbacks:
        callbackName:
          http://client-url.com/events:
            post:
              tags:
                - Transfer
              requestBody:
                content:
                  application/json:
                    schema: null
              responses:
                '200':
                  description: OK
servers:
  - url: https://trp.travel-rule.com
    description: Production
  - url: https://trp-stg.travel-rule.com
    description: Dev area
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Identity:
      type: object
      properties:
        name:
          type: string
          example: Binance
        lei:
          type: string
          example: 12345678910
        x509:
          type: string
          example: '---PEM---'
    Generate:
      operationId: jwt
      type: object
      required:
        - firstName
        - lastName
      properties:
        Authorization:
          type: string
        firstName:
          type: string
          description: First name of the beneficiary.
          example: John
        lastName:
          type: string
          description: Last name of the beneficiary.
          example: Snow
        walletAddress:
          type: string
          description: Wallet address of the beneficiary.
          example: 1q2w3e4r5t6y7u8i9o0p
        externalId:
          type: string
          description: >-
            External identifier of the beneficiary in the originator VASP
            system.
          example: user-123456
security:
  - BearerAuth: []
